ITable interface (deprecated)
ITable is deprecated and is provided for backward compatibility only. New applications should use the java.sql.DatabaseMetaData interface from the JDBC Core API.
The ITable interface represents the definition of a table that is part of a relational data source. ITable provides methods to perform the following types of operations:
The ITable interface is part of the Data Access Engine (DAE) service.
To create an instance of the ITable interface, use getTable( ) in the IDataConn interface (deprecated) or getTable( ) in the IColumn interface (deprecated).
Each call to getTable( ) returns a new ITable object rather than returning an existing table object.
Package
com.kivasoft
Methods
Example
// Add a new user to the User table
ITable tbl = conn.getTable("CTLuser");
tbl.allocRow();
tbl.setValueInt(tbl.getColumnOrdinal("UserID"), nameParm.hashCode());
tbl.setValueString(tbl.getColumnOrdinal("AccessLevel"), aclStr);
tbl.setValueString(tbl.getColumnOrdinal("LoginName"), nameParm);
tbl.setValueString(tbl.getColumnOrdinal("Password"), passwordParm);
tbl.setValueDate(tbl.getColumnOrdinal("AddDate"), addDateParm);
tbl.setValueDouble(tbl.getColumnOrdinal("LoginTime"), TimeParm);
if(tbl.addRow(0, null) == 0)
return result(valOut, "User added");
else
return result(valOut, "Failed to add the user");
addRow( )
Inserts a new row in the table.
Syntax
public int addRow(
int dwFlags,
ITrans pTrans)
dwFlags.
Specifies one of the following flags used to execute this insert operation:
pTrans.
ITransobject that contains the transaction associated with this insert operation, or null.
Usage
Use addRow( ) to insert a new record into a table.
Rules
Tips
Return Value
An int value indicating success (zero) or failure (non-zero, such as an invalid transaction object).
Example
// Get a table
ITable table = conn.getTable("OBTransaction");
if (table == null)
{
return handleOBSystemError("Could not access table
OBTransactionType.");
}
// Look up column ordinals for table
int transTypeCol = table.getColumnOrdinal("transType");
int postDateCol = table.getColumnOrdinal("postDate");
int acctNumCol = table.getColumnOrdinal("acctNum");
int amountCol = table.getColumnOrdinal("amount");
// Create transaction object
ITrans transferTrans = createTrans();
if (transferTrans == null)
{
return handleOBSystemError("Could not start transaction");
}
transferTrans.begin();
int rc;
// Allocate row in table for new entry
table.allocRow();
table.setValueString(acctNumCol, fromAcct);
table.setValueInt(transTypeCol, OBDBDefs.TRANSTYPE_WITHDRAWAL);
table.setValueDateString(postDateCol, transDateString);
table.setValueDouble(amountCol, amount.doubleValue() * -1.0);
// Add the row to the table
rc = table.addRow(0, transferTrans);
transferTrans.commit(0);
Related Topics
ITrans interface (deprecated)
allocRow( )
Allocates a new, empty row buffer, replacing the previous row buffer if one exists.
Syntax
public int allocRow()
Usage
Use allocRow( ) to allocate a new row buffer before adding or updating records in a table. The row buffer is a virtual representation of a row in the target table, including all column definitions. The AppLogic writes data values to the row buffer first, then writes the contents of the row buffer to either a new record using addRow( ) or to one or more existing records using updateRow( ).
Rules
Return Value
GXE.SUCCESS if the method succeeds.
Example
// Get a table
ITable table = conn.getTable("OBTransaction");
if (table == null)
{
return handleOBSystemError("Could not access table
OBTransactionType.");
}
// Look up column ordinals for table
int transTypeCol = table.getColumnOrdinal("transType");
int postDateCol = table.getColumnOrdinal("postDate");
int acctNumCol = table.getColumnOrdinal("acctNum");
int amountCol = table.getColumnOrdinal("amount");
// Create transaction object
ITrans transferTrans = createTrans();
if (transferTrans == null)
{
return handleOBSystemError("Could not start transaction");
}
transferTrans.begin();
int rc;
// Allocate row in table for new entry
table.allocRow();
table.setValueString(acctNumCol, fromAcct);
table.setValueInt(transTypeCol, OBDBDefs.TRANSTYPE_WITHDRAWAL);
table.setValueDateString(postDateCol, transDateString);
table.setValueDouble(amountCol, amount.doubleValue() * -1.0);
// Add the row to the table
rc = table.addRow(0, transferTrans);
deleteRow( )
Deletes one or more rows in the table.
Syntax
public int deleteRow(
int dwFlags,
String szWhere,
ITrans pTrans)
dwFlags.
Specifies one of the following flags used to execute this delete operation:
szWhere.
Selection criteria expression for one or more rows to delete. The syntax is the same as the SQL WHERE clause, only without the WHERE keyword. Use ANSI 92-compliant syntax. If an empty string is specified, all rows in the table are deleted.
pTrans.
ITrans object that contains the transaction associated with this delete operation, or null.
Rules
Tip
Alternatively, the AppLogic can delete records by passing a SQL DELETE statement using setSQL( ) in the IQuery interface (deprecated), then executing the query. The statement must comply with ANSI 92 SQL syntax.
Return Value
GXE.SUCCESS if the method succeeds.
Example
ITable tbl=conn.getTable("CTLcatalog");
if(tbl==null)
return result("Cannot find table: "+"CTLcatalog");
// Otherwise, delete the row with product specified in prodStr
tbl.deleteRow(0, "ProductID"+"="+prodStr, null);
Related Topics
ITrans interface (deprecated)
enumColumnReset( )
Resets the column enumeration to the first column in the table.
Syntax
public int enumColumnReset()
Usage
Use enumColumnReset( ) before iterating through and retrieving columns in a table. enumColumnReset( ) 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
String htmlString;
IColumn col;
ITable tbl = conn.getTable("Products");
htmlString += "<h2>Products Table</h2>";
tbl.enumColumnReset();
while ((col = tbl.enumColumns()) != null) {
htmlString += "Column Name = ";
htmlString += col.getName();
htmlString += ", Column Type = ";
htmlString += col.getType();
htmlString += "<br>";
};
return result(htmlString)
enumColumns( )
Returns the definition of the next column in the table.
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 client code 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 table 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
String htmlString;
IColumn col;
ITable tbl = conn.getTable("Products");
htmlString += "<h2>Products Table</h2>";
tbl.enumColumnReset();
while ((col = tbl.enumColumns()) != null) {
htmlString += "Column Name = ";
htmlString += col.getName();
htmlString += ", Column Type = ";
htmlString += col.getType();
htmlString += "<br>";
};
return result(htmlString)
Related Topics
IColumn interface (deprecated)
getColumn( )
Returns the definition of a column with the specified name.
Syntax
public IColumn getColumn(
String szColumn)
szColumn.
Name of the column to retrieve.
Usage
Use getColumn( ) when the column definition is unknown but its name is known. The AppLogic can use the IColumn object to determine other characteristics about the column, such as its data type, size, whether nulls are allowed, and so on.
Rule
The specified column name must exist in the table.
Return Value
IColumn object for the specified column, or null for failure (such as an invalid column name).
Example
ITable tbl = conn.getTable("Products");
// Obtain column definitions
IColumn colProd = tbl.getColumn("ProductId")
IColumn colCat = tbl.getColumn("CategoryId")
IColumn colPrdName = tbl.getColumn("ProductName")
IColumn colPrice = tbl.getColumn("Price")
. . . manipulate columns using IColumn methods . . .
Related Topics
IColumn interface (deprecated)
getColumnByOrd( )
Returns the definition of the column in the specified ordinal position.
Syntax
public IColumn getColumnByOrd(
int Ordinal)
Ordinal.
Ordinal number (position) of the column in the table. The first column is 1, the second column is 2, and so on.
Usage
Use getColumnByOrd( ) when the column definition is unknown but its position in the table is known, such as when iterating through columns in the table. The AppLogic can use the IColumn object to determine other characteristics about the column, such as its name, data type, size, whether nulls are allowed, and so on.
Rule
The specified column number must exist in the table.
Tips
Return Value
IColumn object for the specified column, or null for failure (such as an invalid column number).
Example
// Obtain information about all columns in the table
ITable tbl = conn.getTable("Products");
int i = 1;
int maxCols = tbl.getNumColumns();
for (i <= maxCols; i++) {
IColumn col = tbl.getColumnByOrd(i);
. . . manipulate column using IColumn methods . . .
}
Related Topics
IColumn interface (deprecated)
getColumnOrdinal( )
Returns the ordinal position of the column specified by name.
Syntax
public int getColumnOrdinal(
String szColumn)
szColumn.
Name of the column.
Usage
Use getColumnOrdinal( ) when the ordinal position of a column is unknown and is required for subsequent operations. For example, the ordinal position of a column is a required parameter value for the setValue**( ) methods, such as setValueString( ) and setValueInt( ).
Rule
The specified column name must exist in the table.
Return Value
An int value representing the ordinal position of the specified column, or zero for failure (such as an invalid column name). The first column is 1, the second column is 2, and so on.
Example
// Get a table
ITable table = conn.getTable("OBTransaction");
if (table == null)
{
return handleOBSystemError("Could not access table
OBTransactionType.");
}
// Look up column ordinals for table
int transTypeCol = table.getColumnOrdinal("transType");
int postDateCol = table.getColumnOrdinal("postDate");
int acctNumCol = table.getColumnOrdinal("acctNum");
int amountCol = table.getColumnOrdinal("amount");
Related Topics
IColumn interface (deprecated)
getDataConn( )
Returns the data connection object associated with the data source in which the table is defined.
Syntax
public IDataConn getDataConn()
Usage
Use getDataConn( ) when the data connection associated with the table is unknown and is required for subsequent operations.
Tip
The IDataConn object that getDataConn( ) returns may not be equal (==) to the IDataConn object that createDataConn( ), in the AppLogic class (deprecated), returned.
Return Value
IDataConn object for the table, or null for failure.
Related Topics
IDataConn interface (deprecated)
getName( )
Returns the name of the table.
Syntax
public String getName()
Usage
Use getName( ) when the name of the table is unknown and is required for subsequent operations.
Return Value
Name of the table represented by the ITable object, or null for failure (such as a memory allocation error).
getNumColumns( )
Returns the number of columns in the table object.
Syntax
public int getNumColumns()
Usage
Use getNumColumns( ) when the number of columns defined in the table is unknown and is required for subsequent operations. When iterating through columns in a table, the AppLogic can use this information to specify the maximum number of iterations.
Return Value
An int value representing the number of columns in the table object, or zero for failure (such as a table with no columns defined).
Example
// Obtain information about all columns in the table
ITable tbl = conn.getTable("Products");
int i = 1;
int maxCols = tbl.getNumColumns();
for (i <= maxCols; i++) {
IColumn col = tbl.getColumnByOrd(i);
. . . manipulate column using IColumn methods . . .
}
setValueBinary( )
Specifies a BINARY value of a column in the row buffer.
Syntax
public int setValueBinary(
int Ordinal,
byte[] pValue,
int nOffset,
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.
pValue.
A byte array expression to assign to the column.
nOffset.
Number of bytes to skip from the beginning of the byte array. This value specifies the starting point within the array.
nLength.
Number of bytes to set for the byte array.
Usage
Use setValueBinary( ) for BINARY data of which the total size is equal to or smaller than 64K.
Rules
Tip
Use setValueBinaryPiece( ) for LONGBINARY, LONGVARBINARY, or equivalent type values.
Return Value
GXE.SUCCESS if the method succeeds.
setValueBinaryPiece( )
Specifies a LONGBINARY value of a column in the row buffer.
Syntax
public int setValueBinaryPiece(
int Ordinal,
byte[] pValue,
int nOffset,
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.
pValue.
A byte array expression to assign to the column.
nOffset.
Number of bytes to skip from the beginning of the byte array. This value specifies the starting point within the array.
nLength.
Number of bytes to set for the byte array.
Usage
Use setValueBinaryPiece( ) to specify LONGBINARY data. LONGBINARY data must be added in 64K increments, therefore, you must use setValueBinaryPiece( ) several times to add the data.
Rules
Tip
Use setValueBinary( ) for BINARY, VARBINARY, or equivalent type values.
Return Value
GXE.SUCCESS if the method succeeds.
setValueDateString( )
Specifies the Date value of a column in the row buffer.
Syntax
public int setValueDateString(
int Ordinal,
String pValue)
Ordinal.
Ordinal number (position) of the target column in the table. The first column is 1, the second column is 2, and so on.
pValue.
A date expression to assign to the column. Use one of the following formats:
Rule
The AppLogic must call allocRow( ) before attempting to write to the row buffer.
Return Value
GXE.SUCCESS if the method succeeds.
Example
// Get a table
ITable table = conn.getTable("OBTransaction");
if (table == null)
{
return handleOBSystemError("Could not access table
OBTransactionType.");
}
// Look up a column ordinal
int postDateCol = table.getColumnOrdinal("postDate");
// Allocate a new row and set a datestring value
table.allocRow();
table.setValueDateString(postDateCol, transDateString);
setValueDouble( )
Specifies the double value of a column in the row buffer.
Syntax
public int setValueDouble(
int Ordinal,
double nValue)
Ordinal.
Ordinal number (position) of the target column in the table. The first column is 1, the second column is 2, and so on.
nValue.
A double expression to assign to the column.
Rule
The AppLogic must call allocRow( ) before attempting to write to the row buffer.
Return Value
GXE.SUCCESS if the method succeeds.
Example
// Get a table
ITable table = conn.getTable("OBTransaction");
if (table == null)
{
return handleOBSystemError("Could not access table
OBTransactionType.");
}
// Look up a column ordinal
int amountCol = table.getColumnOrdinal("amount");
// Allocate a new row and set a double value
table.allocRow();
table.setValueDouble(amountCol, amount.doubleValue() * -1.0);
setValueInt( )
Specifies the int value of a column in the row buffer.
Syntax
public abstract int setValueInt(
int Ordinal,
int nValue)
Ordinal.
Ordinal number (position) of the target column in the table. The first column is 1, the second column is 2, and so on.
nValue.
An int expression to assign to the column.
Rule
The AppLogic must call allocRow( ) before attempting to write to the row buffer.
Return Value
GXE.SUCCESS if the method succeeds.
Example
// Get a table
ITable table = conn.getTable("OBTransaction");
if (table == null)
{
return handleOBSystemError("Could not access table
OBTransactionType.");
}
// Look up a column ordinal
int transTypeCol = table.getColumnOrdinal("transType");
// Allocate a new row and set an Int value
table.allocRow();
table.setValueInt(transTypeCol, OBDBDefs.TRANSTYPE_WITHDRAWAL);
setValueString( )
Specifies the String value of a column in the row buffer.
Syntax
public int setValueString(
int Ordinal,
String pValue)
Ordinal.
Ordinal number (position) of the target column in the table. The first column is 1, the second column is 2, and so on.
pValue.
A String expression to assign to the column.
Rule
The AppLogic must call allocRow( ) before attempting to write to the row buffer.
Return Value
GXE.SUCCESS if the method succeeds.
Example
// Get a table
ITable table = conn.getTable("OBTransaction");
if (table == null)
{
return handleOBSystemError("Could not access table
OBTransactionType.");
}
// Look up a column ordinal
int acctNumCol = table.getColumnOrdinal("acctNum");
// Allocate a new row and set a string value
table.allocRow();
table.setValueString(acctNumCol, fromAcct);
setValueText( )
Specifies a TEXT value of a column in the row buffer.
Syntax
public int setValueText(
int Ordinal,
String pValue,
int nOffset,
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.
pValue.
A string expression to assign to the column.
nOffset.
Number of characters to skip from the beginning of the string.
nLength.
Number of characters to set.
Usage
Use setValueText( ) for TEXT data, or database equivalent, of which the total size is equal to or smaller than 64K.
Rules
Tip
Use setValueTextPiece( ) for LONGTEXT or equivalent type values.
Return Value
GXE.SUCCESS if the method succeeds.
setValueTextPiece( )
Specifies a LONG TEXT value of a column in the row buffer.
Syntax
public int setValueText(
int Ordinal,
String pValue,
int nOffset,
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.
pValue.
A string expression to assign to the column.
nOffset.
Number of characters to skip from the beginning of the string.
nLength.
Number of characters to set.
Usage
Use setValueTextPiece( ) for LONGTEXT data. LONGTEXT values must be added in 64K increments, therefore, you must call setValueTextPiece( ) repeatedly to add the data.
Rules
Tip
Use setValueText( ) for TEXT or equivalent type values.
Return Value
GXE.SUCCESS if the method succeeds.
updateRow( )
Modifies one or more rows in the table with the contents of the row buffer.
Syntax
public int updateRow(
int dwFlags,
String szWhere,
ITrans pTrans)
dwFlags.
Specifies one of the following flags used to execute this update operation:
szWhere.
Selection criteria expression for one or more rows to update. The syntax is the same as the SQL WHERE clause, only without the WHERE keyword. Use ANSI 92-compliant syntax. If an empty string is specified, all rows in the table are updated.
pTrans.
ITrans object that contains the transaction associated with this update operation, or null.
Rules
Tips
Return Value
GXE.SUCCESS if the method succeeds.
Example
// Obtain the definition for the Catalog table
ITable tbl=conn.getTable("CTLcatalog");
if(tbl==null)
return result("Cannot find table: "+"CTLcatalog");
tbl.allocRow();
int cProductId=tbl.getColumnOrdinal("productId");
int cCategory=tbl.getColumnOrdinal("category");
int cName=tbl.getColumnOrdinal("name");
int cPrice=tbl.getColumnOrdinal("price");
int cDesc=tbl.getColumnOrdinal("desc");
int cImage1=tbl.getColumnOrdinal("image1");
int cTemplate=tbl.getColumnOrdinal("template");
int cInventory=tbl.getColumnOrdinal("inventory");
int cReorder=tbl.getColumnOrdinal("reorder");
if((cProductId*cCategory*cName*cPrice*cDesc*cImage1*cTemplate*cReorder)
==0)
return result("Cannot map columns on table:
"+"Catalog");
// Set up the table columns
tbl.setValueInt(cCategory, category);
tbl.setValueString(cName, name);
tbl.setValueDouble(cPrice, price);
tbl.setValueString(cDesc, desc);
tbl.setValueString(cImage1, image1);
tbl.setValueString(cTemplate, template);
tbl.setValueInt(cInventory, inventory);
tbl.setValueInt(cReorder, reorder);
if(option==ADD)
{
valIn.setValString("productId", prodStr);
tbl.setValueInt(cProductId, productId);
tbl.addRow(0, null);
}
else
tbl.updateRow(0, "productId"+"="+prodStr, null);
Related Topics
ITrans interface (deprecated)
|
Previous
