The AppLogic class is deprecated and is provided for backward compatibility only. AppLogics are not part of NAS's new application model, which is based on standards defined in the servlet, EJB, and JDBC specifications. The AppLogic class is provided so that existing AppLogics continue to be supported. However, new applications should avoid calling AppLogic methods whenever possible.

import com.kivasoft.applogic.*;

public class myAppLogic extends AppLogic {

   public int execute() {

   /* Override execute() method with AppLogic code */

      return result("Hello, world!\n");

   }

}

import java.lang.*;

import com.kivasoft.*;

import com.kivasoft.types.*;

import com,kivasoft.util.*;

import com.kivasoft.applogic.*;



public class mySimpleAppLogic extends AppLogic {

   public int execute() {

      log("The execute method got called.");

      log("I can do anything I want here, such as");

      log("run queries, generate reports, update tables,");

      log("and log messages like this one.");

      return GXE.SUCCESS;

   }

}

public IDataConn createDataConn(

	int flags,

	int driver,

	String datasource,

	String database,

	String username,

	String password)

public IDataConn createDataConn(

	int flags,

	int driver,

	IValList prop,

	IContext context)

flags. One or more optional flags used for connecting to the specified data source.

• To try to use a cached connection, if one is available, specify GX_DA_CONN_FLAGS.GX_DA_CACHED. If no cached connections are currently available, a new one is created.
• To always create a new connection (instead of using a cached connection), specify GX_DA_CONN_FLAGS.GX_DA_NEW.
• To retry if a connection is not available, specify GX_DA_CONN_FLAGS.GX_DA_CONN_BLOCK.
• To return a failure immediately after the first attempt if a connection is not available, specify GX_DA_CONN_FLAGS.GX_DA_CONN_NOBLOCK.

driver. Specify one of the following static variables in the GX_DA_DAD_DRIVERS class:

datasource. Name of the data source to connect to. Used for databases that organize data into data source, database, and table objects and sub-objects. For example, a data source for Accounting might contain separate databases for GL, AP, and AR. Each database, such as Accounts Payable, might be a collection of individual tables, such as a vendor table, purchase order table, materials table, and so on. See your database server documentation for more information.

database. Name of the database to connect to. Used for database servers that organize data into databases and tables. See your database server documentation for more information.

username. Login user name that is valid for the specified database.

password. Login password that is valid for the specified user name and database.

props. IValList of connection-specific information required to log in to the data source. Use the following keys for the connection parameters:

• "DSN" for the data source name.
• "DB" for the database name.
• "USER" for the user name.
• "PSWD" for the password.

context. A pointer to the IContext object, which provides access to Netscape Application Server services. Specify null.

• Call createDataConn( ) before running any other database operations requiring a data connection object.
• Your network and the database server must be correctly configured and running so that the AppLogic on your application server can log into the database management system with which it will communicate.
• The data source name, database name, user name, and password must be valid for the database management system to which you want to connect.
• The AppLogic must log in with sufficient access rights to perform all operations it attempts on the data source.

• Before logging in to the database, the AppLogic should check the user's security level to verify sufficient access rights to perform intended operations on the database.
• The Data Access Engine (DAE) manages database connections and related housekeeping tasks, such as shutdown and cleanup. While the DAE performs these tasks automatically and intermittently, an AppLogic can also explicitly close data connections using closeConn( ) in the IDataConn interface.
• Before using an ODBC connection, you must use the ODBC administration utility supplied with your database software to define and name a data source. For more information about how to do this, refer to your ODBC documentation.
• To connect to a Sybase database, specify nullfor the datasource, and specify the database in the form of server:database_name. For example:

devds003:dnet00a

• A connection object can only be used by one thread at a time. When you need to access a database, get the connection object and save it in a local variable. When you're done, close the connection. For example:

Connection conn = DataSource.getConnection();

// code for database access

conn.close();

// Method to open a connection to a database

protected com.kivasoft.IDataConn getOBDataConn()

   {

      String username = "kdemo";

      String password = "kdemo";

      IDataConn newDataConn = createDataConn(0,

              GX_DA_DAD_DRIVERS.GX_DA_DRIVER_ODBC,

              /* Datasource name. */ "ksample",

              /* Database name.   */ "",

              /* userName.        */ username,

              /* password.        */ password);



      if (newDataConn == null)

      {

         log("ERROR: Could not create database connection");

      }

         return newDataConn;

   }

public IDataConnSet createDataConnSet(

	int flags)

flags. Specify 0. Internal use only.

IDataConnSet connSet;

connSet = createDataConnSet(0);

// Specify query / db connection pairs

connSet.addConn("employee", conn_empDB);

connSet.addConn("sales", conn_salesDB);

IHierQuery hqry;

// Load the GXQ file with the db connection set

hqry = loadHierQuery("employeeReport.gxq",connSet, 0, null);



// Run the report

evalTemplate("employeeReport.html", hqry);

public IHierQuery createHierQuery()

• Use createQuery( ) instead for simple, flat queries requiring tabular, non-nested output that is merged with HTML templates.
• To use a hierarchical query, an AppLogic first creates each individual flat query and defines its selection criteria. Next, it creates the IHierQuery object with createHierQuery( ), then calls addQuery( ) repeatedly to add a child query to a parent query for each level of detail in the hierarchical query.
• Alternatively, an AppLogic can create a hierarchical query by loading a query file using loadHierQuery( ). With this technique, the Netscape Application Server can cache query objects to service requests for identical queries more quickly.

// 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)== GXE.SUCCESS)

   return result("");

else

   return result("Failed to Generate HTML");

}

// Create the flat query

IQuery qry = createQuery();

qry.setTables("CTLusers");

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

qry.setWhere("UserId > 100");



// 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)

. . .

public IMailbox createMailbox(

	String pHost,

	String pUser,

	String pPassword,

	String pUserAddr)

pHost. Address of POP and SMTP server, such as mail.myOrg.com. If the POP and SMTP servers are running on different hosts, you must use two separate createMailbox( ) calls.

pUser. Name of user's POP account, such as jdoe.

pPassword. Password for POP server.

pUserAddr. Return address for outgoing mail, such as john@myOrg.com. Usually the electronic mail address of the user sending the message.

• POP (post-office protocol) servers process incoming mail and forward messages to the recipient's mailbox.
• SMTP (simple mail transport protocol) servers forward outgoing mail to the addressee's mail server.

• The specified user account and password must be valid for the specified POP host name.
• The user address must be valid for the specified SMTP server.

public IQuery createQuery()

• To query a database, the AppLogic first uses createQuery( ) to create the query object, then constructs the query selection criteria using methods in the IQuery interface, and finally runs the query on a database server. The AppLogic can process results using methods in the IResultSet interface.
• Alternatively, AppLogic can pass a SQL SELECT statement directly to the database server using setSQL( ) in the IQuery interface.
• To retrieve data with nested levels of information, use createHierQuery( ) instead.

// Create the flat query object

IQuery qry = createQuery();

// Set up the query

qry.setTables("CTLcust");

qry.setFields("CustomerID, Customer");

qry.setWhere("Customer"+"='"+String.valueOf(custId)+"'");



// Execute the query

IResultSet rs = conn.executeQuery(0, qry, null, null);



// Check for a result set with rows

if((rs!=null)&&(rs.getRowNumber()>0))

   return result("Sorry, this user ("+

   firstName+" "+lastName+") already exists");

// Otherwise, process the result set . . .

public ISession2 createSession(

	int dwFlags,

	int dwTimeout,

	String pAppName,

	String pSessionID,

	ISessionIDGen pIDGen)

dwFlags. Specify one of the following flags, or 0 to use the default system settings:

• GXSESSION.GXSESSION_LOCAL to make the session visible to AppLogics in the local process only.
• GXSESSION.GXSESSION_CLUSTER to make the session visible to all AppLogics within the cluster.
• GXSESSION.GXSESSION_DISTRIB to make the session visible to all AppLogics on all Netscape Application Servers.
• GXSESSION.GXSESSION_TIMEOUT_ABSOLUTE to specify that the session expires at a specific date and time. Do not use this flag. It is currently unimplemented but reserved for future use.
• GXSESSION.GXSESSION_TIMEOUT_CREATE to specify that the session expires n seconds from the time the session was created.

dwTimeout. Session timeout, in number of seconds, or zero for no timeout. The meaning of timeout depends on the timeout flag specified in dwFlags. A value of 0 means the session is deleted when the AppLogic calls destroySession( ).

pAppName. Name of the application associated with the session. The application name enables the Netscape Application Server to determine which AppLogics have access to the session data. Specify null to use the application name assigned to the AppLogic during kreg registration.

pSessionID. The session ID to use. Specify null to use the default ID generated by the system.

pIDGen. The session ID generation object used to generate session IDs. Specify null.

ISession2 sess;

sess = getSession(0, "Catalog", null);

if (sess == null)

{

   log("Could not get session, creating a new one");

   sess = createSession(GXSESSION.GXSESSION_DISTRIB, 0,

                null, null, null);

public ITrans createTrans()

• Use this method in conjunction with addRow( ),updateRow( ), and deleteRow( ) methods in the ITable interface and executeQuery( )in the IDataConn interface.
• To manage transaction processing operations, use createTrans( ) to create an instance of the ITrans interface, then use begin( ), commit( ), and rollback( ) in the ITrans interface to begin, commit, and rollback the transaction, respectively.

// Create and begin a transaction

ITrans trx = createTrans();

trx.begin();



// 1) Process the credit card

if(!processCreditCard(cusId, card, number, expirationDate, trx)) {

   trx.rollback();

   return result("Could not process the credit card information"); }



// 2) Process the invoice record

InfoHolder info=new InfoHolder();

if(!makeInvoiceRecord(cusId, number, trx, info)) {

   trx.rollback();

   return result("Could not create the invoice record"); };



// 3) Process products on the invoice

if(!makeInvoiceEntries(info.invoiceId, trx)) {

   trx.rollback();

   return result("Can't create product records"); };



// 4) Process optional shipping information

if(shippingInfo && !makeShippingRecord(info.invoiceId, trx, addr1, 
addr2, city, state, zip)) {

   trx.rollback();

   return result("Could not create the shipping information record"); };



// 5) Process the inventory for each purchased product

if(!reduceProductInventory(trx)) {

   // Problem occurred - abandon everything

   trx.rollback();

	return result("Could not reduce inventory"); 

}



// No problem occurred - save everything

trx.commit(0);

// Return success message / report

public int deleteCache(

	String guid)

guid. The guid that identifies the AppLogic whose result cache to delete. Specify null to delete the current AppLogic's cache.

• To clear an AppLogic's result cache, but continue caching, use removeAllCachedResults( ).
• To clear a specific result from the cache, use removeCachedResult( ).

int hr;

String guid = valIn.getValString("applogic");



hr = deleteCache(guid);



if (hr == GXE.SUCCESS)

   return result("Successfully deleted cache")

else

   return result("Failed to delete cache");

public int destroySession(

	ISessionIDGen pIDGen)

pIDGen. The session ID generation object used to generate session IDs. Specify null .

public int evalOutput(

	String templatePath,

	IHierQuery query,

	ITemplateMap map,

	IStream stream,

	IValList props);

public int evalOutput(

	String templatePath,

	ITemplateData data,

	ITemplateMap map,

	IStream stream,

	IValList props);

templatePath. Path to the template file used to create the report. At a minimum, specify the file name. Do not specify the filename extension; for example, specify "report" instead of "report.html". The evalOutput( ) method automatically uses the correct filename extension depending on the client type. Use a relative path whenever possible. The Netscape Application Server first searches for the template using the specified path. If the template is not found, the Netscape Application Server uses the configured TEMPLATE\PATH search path to find it. For more information on configuring the search path, see Administration Guide.

query. Hierarchical query object from which evalOutput( )createTrans( ) derives the hierarchical result set to merge with the template. The Template Engine runs the query on the database server. To specify this parameter, the AppLogic must first create the specified hierarchical query, using createHierQuery( ) in the AppLogic class, and then define it using methods in the IHierQuery interface or calling loadHierQuery( ).

map. Field map that links template fields to calculated values. Fields in the template are expressed with the cell type gx tags. Additionally, the map can be used to map source data with a non-matching field name but identically-formatted data. To specify this parameter, the AppLogic should instantiate the TemplateMapBasic class, add template / field mappings using put( ) in the ITemplateMap interface, then pass the populated ITemplateMap object to evalOutput( ) for template processing.

stream. The output stream where results will be captured for subsequent retrieval and processing. Specify null to use the default stream, which sends results back to the client. To specify this parameter, an AppLogic creates a stream buffer object from IStreamBuffer, which it passes to evalOutput( ). After evalOutput( ) returns, the AppLogic calls getStreamData( ) in the IStreamBuffer interface to retrieve the contents of the buffer as an array of byte values.

data. ITemplateData object containing data. This can be a hierarchical result set from executing a hierarchical query or it can be data programmatically organized in memory. To specify this data in memory, an AppLogic must first instantiate the TemplateDataBasic class (or implement your own version of the ITemplateData interface), populate the ITemplateData object with rows of hierarchical data, then pass it to evalOutput( ) for template processing.

props. Specify null.

• If possible, write queries so that field names in the result set match the field names in the template. Otherwise, you must use an ITemplateMap object to map field names.
• To create an GXML file, you can convert an HTML template file with the khtml2gxml utility. This utility strips HTML tags from the template file and saves the file as a GXML file. The following is an example of how to run the utility from the command line:

khtml2gxml mytemplate.html

// Create a hierarchical query used for template processing

IHierQuery hqry = createHierQuery();



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

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



// Pass hierarchical query to evalOutput() for reporting

if(evalOutput("apps/template/userinfo", hqry)== GXE.SUCCESS)

   return result("");

else

   return result("Failed to Generate HTML");

}

public int evalTemplate(

	String path,

	IHierQuery query)

public int evalTemplate(

	String path,

	IHierQuery query,

	ITemplateMap map,

	IStream stream)

public int evalTemplate(

	String path,

	ITemplateData data,

	ITemplateMap map)

path. Path to the HTML template file used to create the report. At a minimum, specify the file name. Use a relative path whenever possible. The Netscape Application Server first searches for the template using the specified path. If the template is not found, the Netscape Application Server uses the configured TEMPLATE\PATH search path to find it. For more information on configuring the search path, see the Administration Guide.

query. Hierarchical query object from which evalTemplate( ) derives the hierarchical result set to merge with the HTML template. The Template Engine runs the query on the database server. To specify this parameter, the AppLogic must first create the specified hierarchical query, using createHierQuery( ) in the AppLogic class, and then define it using methods in the IHierQuery interface or calling loadHierQuery( ).

map. Field map that links template fields to calculated values. Fields in the template are expressed with the cell type gx tags. Additionally, the map can be used to map source data with a non-matching field name but identically-formatted data. To specify this parameter, the AppLogic should instantiate the TemplateMapBasic class, add template / field mappings using put( ) in the ITemplateMap interface, then pass the populated ITemplateMap object to evalTemplate( ) for template processing.

stream. The output stream where results will be captured for subsequent retrieval and processing. Specify null to use the default stream, which sends results back to the client. To specify this parameter, an AppLogic creates a stream buffer object from IStreamBuffer, which it passes to evalOutput( ). After evalTemplate( ) returns, the AppLogic calls getStreamData( ) in the IStreamBuffer interface to retrieve the contents of the buffer as an array of byte values.

data. ITemplateData object containing data. This can be a hierarchical result set from executing a hierarchical query or it can be data programmatically organized in memory. To specify this data in memory, an AppLogic must first instantiate the TemplateDataBasic class (or implement your own version of the ITemplateData interface), populate the ITemplateData object with rows of hierarchical data, then pass it to evalTemplate( ) for template processing.

• If your AppLogic requires the flexibility of returning different output depending on the client—a Web browser or another AppLogic—use evalOutput( ) instead.
• If possible, write queries so that field names in the result set match the field names in the template. Otherwise, you must use an ITemplateMap object to map field names.

// 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)==GXE.SUCCESS)

   return result("");

else

   return result("Failed to Generate HTML");

}

public int execute()

• In general, your AppLogic class will inherit from the AppLogic class and override the default behavior of the execute( ) method, such as retrieving an orders report from a database.
• The AppLogic can analyze the valIn member variable for input arguments using methods in the IValList interface.
• The AppLogic can modify the valIn member variable using methods in the IValList interface.

package gxApp.sample

import java.lang.*;

import com.kivasoft.*;

import com.kivasoft.types.*;

import com,kivasoft.util.*;

import com.kivasoft.applogic.*;



public class HelloWorldAppLogic extends AppLogic {

public int execute() {

// Simple code that overrides execute() method

   return result("Hello world!");

   }

}

public IAppEvent getAppEvent()

public ISession2 getSession(

	int dwFlags,

	String appName,

	ISessionIDGen pIDGen)

dwFlags. Specify 0 (zero).

pAppName. Name of the application associated with the session. The application name enables the Netscape Application Server to determine which AppLogics have access to the session data. Specify null to use the application name assigned to the AppLogic during kreg registration.

pIDGen. The session ID generation object used to generate session IDs. Specify null.

ISession2 sess;

sess = getSession(0, "Catalog", null);

if (sess == null)

{

   log("Could not get session, creating a new one");

   sess = createSession(GXSESSION.GXSESSION_DISTRIB, 0,

                null, null, null);

public class ProductRestock extends AppLogic

{

  public int execute()

    {

      try {

         ISession2 mySess;

         mySess = getSession(0, null, null);

         if (mySess == null) {

            log("missing session");

            return evalOutput("kivaapp/shop/please_login", 

                  (ITemplateData) null,

                  (ITemplateMap)  null, null, null);

         }

         // Check to see if the current role is authorized

         // to update inventory.

         //

         if (isAuthorized("Shop_Inventory", "WRITE") != 

					GXACLPERMSTATUS.GXACL_ALLOWED)

         {

            log("unauthorized access: Shop_Inventory");

            return evalOutput("kivaapp/shop/no_access", 

                  (ITemplateData) null,

                  (ITemplateMap)  null, null, null);

         }

         // Record the inventory restock transaction.

public IState2 getStateTreeRoot(

	int dwFlags,

	String pName)

dwFlags. Specify one of the following flags or zero to use the default settings:

• GXSTATE.GXSTATE_LOCAL to make the node visible to the local process only.
• GXSTATE.GXSTATE_CLUSTER to make the node visible to all AppLogics within the cluster.
• GXSTATE.GXSTATE_DISTRIB, the default, to make the node visible to all AppLogics on all servers.

pName. The name of the root node. If a node with this name doesn't already exist, a new node is created.

IState2 tree = getStateTreeRoot(GXSTATE.GXSTATE_DISTRIB, "Grammy");



if (tree!=null)

{

   IState2 child = tree.getStateChild("Best Female Vocal");

   if (child == null)

   {

      child = tree.createStateChild("Best Female Vocal", 0,

        GXSTATE.GXSTATE_DISTRIB);

public int isAuthorized(

	String pTarget,

	String pPermission)

public int isAuthorized(

	String pDomain,

	String pTarget,

	String pPermission,

	int method,

	int flags,

	ICred pCred,

	IObject pEnv)

pDomain. The type of Access Control Lists (ACL). An ACL (created by the server administrator) defines the type of operations, such as Read or Write, that a user or group can perform. There are two types of ACLs: AppLogic and general. For this parameter, specify one of the following strings, which specifies the type of ACL to check for this user:

pTarget. The name of the ACL, if the ACL is a general type. If the ACL is an AppLogic ACL, specify the AppLogic name or GUID string.

pPermission. The type of permission, for example, "EXECUTE."

method. Specify 0.

flags. Specify 0.

pCred. Specify null.

pEnv. Specify null.

if (isAuthorized("MonthlyForecast", "READ") != 
GXACLPERMSTATUS.GXACL_ALLOWED)

   return result("<html><body>sorry no access</body></html>);

else

// run monthly forecast report

public boolean isCached()

// Determine whether AppLogic is cached

// before setting cache criteria

if(!isCached()) {

   log("Setting agent cache criteria");

   if(setCacheCriteria(60, 3, "category")!=0)

      log("Could not set agent cache criteria");

   else

      log("Succeeded in setting agent cache criteria");

   }

else

      log("Not setting agent cache criteria");

public IHierQuery loadHierQuery(

	String pFileName, 

	IDataConnSet pDataConnSet,

	int flags,

	IValList pParams)

pFileName. Name of the query (.GXQ) file, including the path. Use a relative path when possible.

• The file for a hierarchical query contains several SQL SELECT statements (compliant with ANSI SQL89) with the following additions:

• Each query is preceded by the following line:

  query queryName using (driverCode, DSN, UserName) is

• For a child query, append the following line after the SQL SELECT statement:

  join currentQueryName to parent parentName where

  currentQueryName.table.column = parentName.colorAlias

• In the query file, do not use any semicolons (;) or other vendor-specific SQL statement terminators.

pDataConnSet. Collection of query name/data connection pairs. The query names in the collection must match the named queries in the query file. The associated IDataConn object identifies the data connection for the query.

flags. Specify 0 (zero). Internal use only.

pParams. IValList of query file parameters, or null. A collection of placeholders for the WHERE clause. A placeholder may be a name or a number. It is prefixed by a colon (:) character. The placeholders can be replaced by specifying replacement values in the ValList parameter.

• AppLogic must first call createDataConnSet( ) to create an IDataConnSet, then add query name / data connection pairs using addConn( ) in the IDataConnSet interface.
• The query names in the collection must match the query names in the query file.

/* STATES */

query STATES using (ODBC, kstates, kuser) is

select STATES.STATE as STATES_STATE

from STATES

where (STATES.REGION = ':REGION')

order by STATES.STATE asc



/* DETAILS */

query DETAILS using (ODBC, kdetails, kuser) is

select COUNTIES.COUNTYNAM as COUNTIES_COUNTYNAM,

   COUNTIES.POP as COUNTIES_POP,

   COUNTIES.STATE as COUNTIES_STATE

from COUNTIES

order by COUNTIES.COUNTYNAM asc



join DETAILS to parent STATES

where DETAILS.COUNTIES.STATE = 'STATES.STATES_STATE'

IDataConnSet connSet;

connSet = createDataConnSet(0);



// Create database connections

IDataConn conn_detailDB = createDataConn(0, 
GX_DA_DAD_DRIVERS.GX_DA_DRIVER_DEFAULT, "kdetails", "", "kuser", 
"kpassword");



IDataConn conn_statesDB = createDataConn(0, 
GX_DA_DAD_DRIVERS.GX_DA_DRIVER_ODBC, "kstates", "", "kuser", 
"kpassword");



// Specify query / db connection pairs

connSet.addConn("DETAILS", conn_detailDB);

connSet.addConn("STATES", conn_statesDB);



// Create IValList that contains the REGION parameter

// value to pass to the hierarchical query

IValList param = GX.CreateValList();

param.setValString("REGION", "WEST");



IHierQuery hqry;

// Load the GXQ file with the db connection set and 

// parameter value

hqry = loadHierQuery("state.gxq", connSet, 0, param);



// Run the report

evalTemplate("state.html", hqry);

public IQuery loadQuery(

	String pFileName,

	String pQueryName,

	int flags,

	IValList pParams)

pFileName. Name of the query (.GXQ) file, including the path. Use a relative path when possible.

• The query file for a flat query contains a SQL SELECT statement (compliant with ANSI SQL89) preceded by the following line:

/* optional comments */

query queryName using (driverCode, DSN, UserName) is

where queryName is the name of the flat query. Do not use any semicolons (;) in the query file.

• In the query file, do not use any semicolons (;) or other vendor-specific SQL statement terminators. The SQL statement may contain placeholders in the WHERE clause.

pQueryName. Name of the query in the query file.

flags. Specify 0 (zero). Internal use only.

pParams. IValList of query file parameters, or null. A collection of placeholders for the WHERE clause. A placeholder may be a name or a number. It is prefixed by a colon (:) character. The placeholders can be replaced by specifying replacement values in the IValList parameter.

/* STATES */

query STATES using (ODBC, kstates, kuser) is

select STATES.STATE as STATES_STATE

from STATES

where (STATES.REGION = ':REGION')

order by STATES.STATE asc

// Create database connection

IDataConn conn = createDataConn(0, 
GX_DA_DAD_DRIVERS.GX_DA_DRIVER_DEFAULT, "kstates", "", "kuser", 
"kpassword");



// Create IValList that contains the REGION parameter

// value to pass to the query

IValList param = GX.CreateValList();

param.setValString("REGION", "WEST");



IQuery qry;

// Load the query file with the parameter value

qry = loadQuery("state.gxq", "STATES", 0, param);



// Execute the query

IResultSet rs = conn.executeQuery(

GX_DA_EXECUTEQUERY_FLAGS.GX_DA_RS_BUFFERING, qry, null, null);

public int log(

	String msg)

public int log(

	int type,

	int category,

	String msg)

msg. Message text to log.

type. Message type. Use one of the following variables:

• GXLOG.GXEVENTTYPE_INFORMATION
• GXLOG.GXEVENTTYPE_ERROR
• GXLOG.GXEVENTTYPE_SYSTEM
• GXLOG.GXEVENTTYPE_WARNING

category. User-defined message category. Do not use the range of values reserved for the Netscape Application Server systems, which is 0 to 65535, inclusive.

// Log a message

log("This is the message text saved to the log");

// Log messages that include String variables

log(firstName+lastName+password+" "+String.valueOf(cusId));

log(GXLOG.GXEVENTTYPE_ERROR", -1, Cannot find table: "+"Shipping");

public int loginSession(

	String name,

	String password)

public int loginSession(

	String pDomain,

	int dwMethod,

	int dwFlags,

	String pName,

	byte[] pAuthData,

	int nAuthData)

name. The login user name.

password. The user password.

pDomain. Specify null.

dwMethod. Specify 0.

dwFlags. Specify 0.

pName. The login user name.

pAuthData. The user password.

nAuthData. The size of the password.

public class Welcome extends AppLogic

{

    public int execute()

   {

      try {



         // Check user login

         if (valIn.getValString("NAME") == null ||

            valIn.getValString("PASSWORD") == null) {

            log("missing login NAME/PASSWORD");

            return evalOutput("kivaapp/shop/login_again", 

                  (ITemplateData) null,

                  (ITemplateMap)  null, null, null);

         }

         // If login succeeds, create a session

         ISession2 mySess;

         mySess = getSession(0, null, null);

         if (mySess == null) {

            mySess=createSession(0, 60000, null, null, null);

            log("created session: " + String.valueOf(mySess != null));

         } else

            log("got session");



         // Now, look up user NAME/PASSWORD in database

         // and see what role the user has.  The database

         // should have a user table which tracks all the

         // users of the online shop application.

         //

         String role;

         role = /* Database lookup here. */ "Shop_Customer";



         // Call loginSession() to set up the session with 

         // that role. Future requests to AppLogics in this 

         // session will now operate under the right role.

         //

         loginSession(role, "");

         saveSession(null);



         // Check to see if the current role is authorized

         // against some of the more advanced operations, 

         // and choose the appropriate main menu page to 

         // return to the user.

         //

         if (isAuthorized("Shop_Inventory", "READ") == 

				 GXACLPERMSTATUS.GXACL_ALLOWED ||

            isAuthorized("Shop_Daily_Forecast", "READ") == 

				 GXACLPERMSTATUS.GXACL_ALLOWED ||

            isAuthorized("Shop_Weekly_Forecast", "READ") == 

				 GXACLPERMSTATUS.GXACL_ALLOWED)

            return evalOutput("mainmenu_advanced", 

                  (ITemplateData) null,

                  (ITemplateMap)  null, null, null);

         return evalOutput("kivaapp/shop/mainmenu_regular", 

               (ITemplateData) null,

               (ITemplateMap)  null, null, null);

      } finally {

      }

   }

}

public int logoutSession(

	int dwFlags)

dwFlags. Specify 0.

public int newRequest(

	String guidSTR)

public int newRequest(

	String guidSTR,

	IValList vIn,

	IValList vOut)

public int newRequest(

	String guidSTR,

	IObject vIn,

	IObject vOut,

	int host,

	int port,

	int flag)

guidSTR . String GUID or name of the AppLogic to execute.

vIn. IValList object containing input parameters to pass to the called AppLogic.

vOut. IValList object containing result values of the called AppLogic.

host. IP address of the Internet host of the Netscape Application Server where the AppLogic is to be executed. Specify 0 to execute the AppLogic locally.

port. Internet port of the Netscape Application Server where the AppLogic is to be executed. Specify 0 to execute the AppLogic locally.

flag. Specify zero.

• Process application logic and return result values in the vOut parameter.
• Process application logic and return the resulting data form (such as a report) by streaming the output or by calling result( ).
• Process application logic and return result values in the vOut parameter as well as return the resulting data form (such as a report) by streaming the output or by calling result( ).

vallist.setValString("gx_client_type", "ocl");

• The calling AppLogic can create new input and output IValLists so as to avoid changing its own input and output IValLists.
• The AppLogic can call another AppLogic, passing its own input and output IValLists. In this case, the called AppLogic accesses the same stream destinations as the calling AppLogic.
• Use newRequestAsync( ) instead of newRequest( ) to execute asynchronous request.
• Called AppLogics might reside on different servers, depending on partitioning and load balancing configurations, might be written in a different language, or might have cached results. The calling AppLogic can be unaware or independent of these conditions.
• Using newRequest( ), you can modularize parts of the application, build dynamic header/footer information and smart reporting templates, and hide complex or confidential business logic in secure submodules or even separate servers.
• Use newRequest( ) judiciously. Each invoked AppLogic uses a certain amount of communications and server resources.

// Call specified AppLogic and pass parameters

newRequest("{E5CA1000-6EEE-11cf-96FD-0020AFED9A65}",

   paramsToModule, paramsReturned);

// Use DisplayBasket AppLogic to display the contents

if(newRequest("DisplayBasket", valIn, valOut)==0){

   return 0;

   }

else

   return result("Cannot execute DisplayBasket AppLogic");

public IOrder newRequestAsync(

	String guidSTR)

public IOrder newRequestAsync(

	String guidSTR,

	IValList vIn,

	IValList vOut)

public IOrder newRequest(

	String guidSTR,

	IObject vIn,

	IObject vOut,

	int host,

	int port,

	int flag)

guidSTR . String GUID or name of the AppLogic to execute.

vIn. IValList object containing input parameters to pass to the called AppLogic.

vOut. IValList evalOutput( ) object containing result values of the called AppLogic.

host. IP address of the Internet host of the Netscape Application Server where the AppLogic is to be executed. Specify 0 to execute the AppLogic locally.

port. Internet port of the Netscape Application Server where the AppLogic is to be executed. Specify 0 to execute the AppLogic locally.

flag. Specify 0.

• Process application logic and return result values in the vOut parameter.
• Process application logic and return the resulting data form (such as a report) by streaming the output or by calling result( ).
• Process application logic and return result values in the vOut parameter as well as return the resulting data form (such as a report) by streaming the output or by calling result( ).

• The specified AppLogic must be accessible to the Netscape Application Server.
• The specified GUID string, input parameters, and output parameters must be valid for the specified AppLogic module.

• To get the current status of the request, use the getState( ) method in the returned IOrder object.
• The calling AppLogic can use GX.WaitForOrder( ) to wait for one or multiple asynchronous requests to return.
• The calling AppLogic can create new input and output IValLists so as to avoid changing its own input and output IValLists.
• The AppLogic can call another AppLogic, passing its own input and output IValLists. In this case, the called AppLogic accesses the same stream destinations as the calling AppLogic. To prevent conflicts in streaming, the calling AppLogic can use GX.WaitForOrder( ) to wait until the called AppLogic is finished.
• Using newRequestAsync( ), you can modularize parts of the application, build dynamic header/footer information and smart reporting templates, and hide complex or confidential business logic in secure submodules or even separate servers.
• Use newRequestAsync( ) judiciously. Each invoked AppLogic uses a certain amount of communications and server resources.

Orders[] = new IOrder[1];

int nOrder;



Orders[0] = newRequestAsync(asyncGUIDStr, valIn, valOut);

if (Orders[0] != null)

{

   log("Successfully invoked async AppLogic\n");

 

   // wait for async applogic to finish (max 100 seconds)

   nOrder = GX.WaitForOrder(Orders, context, 100);

   if (nOrder >= 0)

   {

       return result("Error in executing async request:

			  order wait returned an error");

   }

   else

   {

      getStateIOrder state = Orders[0].getState();

      if (state == null || state.pdwState != GXE.SUCCESS)

         return result("Error in executing async

				 request");

   }

}

else

{

   log("Failed to invoke async AppLogic\n");

}

public int removeAllCachedResults(

	String guid)

guid. The guid that identifies the AppLogic whose result cache to clear. Specify null to clear the current AppLogic's cache.

• To clear an AppLogic's entire result cache and discontinue caching, use deleteCache( ).
• To clear a specific result from the cache, use removeCachedResult( ).

int hr;

String guid = valIn.getValString("applogic");



hr = removeAllCachedResults(guid);

if (hr == GXE.SUCCESS)

   return result("Successfully cleared cached results")

else

   return result("Failed to clear cached results");

public int removeCachedResult(

	String guid,

	IValList criteria)

guid. The guid that identifies the AppLogic whose cached result to clear. Specify null to clear the current AppLogic's cached result.

criteria. An IValList object that contains the criteria for selecting the result to remove. In the IValList object, set a specific value that matches the cache criteria passed to setCacheCriteria( ). For example, if the cache criteria passed to setCacheCriteria( ) was "Salary=40000-60000"), you can remove results where salary is 50000 by setting in the IValList object a "Salary" key to a value of "50000".

• To clear an AppLogic's entire result cache and discontinue caching, use deleteCache( ).
• To clear an AppLogic's entire result cache, but continue caching, use removeAllCachedResults( ).

int hr;

String guid = valIn.getValString("applogic");



IValList resultList = GX.CreateValList();

resultList.setValString("Salary", "50000");



hr = removeCachedResult(guid, resultList);



if (hr == GXE.SUCCESS)

   return result("Successfully deleted specified result")

else

   return result("Failed to delete specified result");

public int result(

	String result)

result. Text representing the result value of the current AppLogic.

• To construct HTML output programmatically, use the Java StringBuffer class to efficiently build up an HTML result, which can then be efficiently converted to a string to be passed in as the input to result( ).
• An AppLogic can cache results for reuse using setCacheCriteria( ).
• Alternatively, the AppLogic can return results using a template. The AppLogic can call evalOutput( ) to merge a dynamically created result set from a hierarchical query with a template to produce formatted results. The result from evalOutput( ) is streamed automatically.

// Return a simple HTML string

public class HelloWorld extends AppLogic {

   public int execute() {

      return result("Hello, world!\n");

   }

}

// Dynamically create the return string

public int execute() {

   String resultStr;

   String text;

   text = valIn.getValString("Incoming Text");

   if (text == null)

      resultStr = "No input text.";

   else if (text.indexOf('-') >= 0)

      resultStr = "Input text has a hyphen.";

   else

      resultStr = "Input text has no hyphen.";

   resultStr = "<HTML>" + resultStr + "</HTML>";

   return result(resultStr);

}

public int saveSession(

	ISessionIDGen pIDGen)

pIDGen. The session ID generation object used to generate session IDs. Specify null.

• The AppLogic needs to call the saveSession( ) method in the AppLogic class at least once to set a cookie. The saveSession( ) method in the interface only saves data to the distributed state store, whereas saveSession( ) in the AppLogic class saves data to the distributed state store and sets a cookie.
• The AppLogic should call saveSession( ) to save changes after updating session data.
• To improve performance, keep smaller amounts of information in the session.

public int setCacheCriteria(

	int timeout,

	int cachesize,

	String criteria)

timeout. Number of seconds the AppLogic result remains in the result cache after the last access. To clear the result cache after a specified time from its creation, use the GXREPOSIT.GXREPOSIT_TIMEOUT_CREATE flag, as shown in the following example: setCacheCriteria(GXREPOSIT.GXREPOSIT_TIMEOUT_CREATE | 300, ...). In this example, the cache is cleared 300 seconds after it is created. Set timeout to zero to clear the result cache and disable caching for this AppLogic.

cachesize. Maximum number of results to be cached for the AppLogic at any time. The result cache stores distinct AppLogic output up to the cachesize limit. If the AppLogic generates another output to cache, the least accessed member of the cache is dropped. Setting cachesize to zero clears the result cache and disables caching for this AppLogic.

criteria. Criteria expression containing a string of comma-delimited descriptors. Each descriptor defines a match with one of the input parameters to the AppLogic. Use the following syntax:

• Do not use caching if real-time results are needed. For example, to ensure current data, caching is not recommended for query operations on highly volatile data.
• Use skipCache( ) to bypass result caching if an error occurred during AppLogic execution.
• Use isCached( ) to test whether caching is currently enabled. Calling isCached( ) is important because it prevents calling setCacheCriteria( ) too many times.
• To change the caching criteria for AppLogic, call setCacheCriteria( ) again, this time specifying different caching criteria. Each subsequent call supersedes the previous call, discarding the current contents of the result cache, and its criteria remain in effect until the next setCacheCriteria( ) call, if applicable.
• To stop caching results, call deleteCache( ). A subsequent call to setCacheCriteria( ) can reactivate caching.

// Verify AppLogic caching before setting cache criteria

if(!isCached())  {

   log("Set criteria to save output from 3 deptcodes");

   if(setCacheCriteria(60, 3, "deptcode")!=0)

      log("Could not set criteria");

   else

      log("Succeeded in setting criteria");

}

else

   log("Not Setting Criteria");

// Cache multiple results for up to 100 values of Department

setCacheCriteria(3600,100,"Department");

// Cache single result for given matching value of Department

setCacheCriteria(3600,1,"Department=Operations");

// Cache multiple results for two matching values of dept

setCacheCriteria(3600,2,"Department=Research | Engineering");

// Cache one result for salary in a range

setCacheCriteria(3600,1,"Salary=40000-60000");

// Cache two results for several parameters

setCacheCriteria(3600, 2, 

    "Department=Sales,Salary=40000-60000");

public int setSessionVisibility(

	String domain,

	String path,

	boolean isSecure)

domain. The domain in which the session is visible.

path. The path to which this session must be visible.

isSecure. If TRUE, the session is visible only to secure servers (HTTPS).

public int setVariable(

	String name,

	String value)

public int setVariable(

	String name,

	String value,

	int timeout,

	String urlPath,

	String urlDomain,

	boolean secure)

name. The name of the value to record for this browser session. The value will appear on any future AppLogic's input IValList under this name.

value. The string value to record.

timeout. Number of seconds before the cookie expires. Applies to HTTP clients only.

urlPath. The subset of URLs in a domain for which the cookie is valid. Applies to HTTP clients only.

urlDomain. The domain for which the cookie is valid. Applies to HTTP clients only.

secure. If a cookie is marked secure, it will be sent only if the communications channel with the host is a secure one. Currently, this means that secure cookies will be sent only to HTTPS (HTTP over SSL) servers. Applies to HTTP clients only.

public int skipCache()

// Skip result caching if an error occurs 

// during AppLogic execution 

public class produceReport extends AppLogic {

   public int execute() {

   if (isCached == false)

      // Set up results cache

      setCacheCriteria(3600, 1, "");

   String result;

   if (. . . Input arguments are not valid . . .) {

      result = "Please enter your employee id...";



      // We don't want the above error prompt to be

      // put into the result cache, so we must 

      // call skipCache.

      skipCache();

      else {

      result = [. . . Generate report . . .];

   }

   return result(result);

   }

}

public synchronized int streamResult(

	String res)

res. The body data to stream. If returning HTML body data, you can use HTML formatting following HTTP body conventions. See your HTTP documentation for more information.

• Alternatively, use evalTemplate( ) to stream HTTP body output. It merges data with an HTML template. As soon as a segment of the output page is finished, evalTemplate( ) streams it out to the Web browser.
• An AppLogic can call streamResultHeader( ) and streamResult( ) repeatedly to stream more results.
• To stream binary data, use streamResultBinary( ).

// Stream header and body, passing the header and body data

// as variables.

streamResultHeader(headerVariable);

streamResult(bodyVariable);

// Stream header or body in several parts, using several

// method calls, starting with the header

streamResultHeader(startHeader);

streamResultHeader(finishHeader);

streamResult(bodyStart);

streamResult(bodyMiddle);

streamResult(bodyEnd);

public synchronized int streamResultBinary(

	byte[] buf,

	int offset,

	int length)

buf. The array from which binary data is streamed.

offset. Index in the array. The starting position in the array to start streaming binary body data.

length. Number of bytes to stream from the array, starting at the specified offset position.

• Alternatively, use evalTemplate( ) to stream HTTP body output. It merges data with an HTML template. As soon as a segment of the output page is finished, evalTemplate( ) streams it out to the waiting Web browser.
• To stream non-binary data, use streamResult( ).

public synchronized int streamResultHeader(

	String hdr)

hdr. The header data to stream. If returning HTTP header data, use the HTTP header conventions, such as the following:

"Content-Type: text/html"

"Location: <redirect url>" 

// Stream header and body, passing the header and body data

// as variables.

StreamResultHeader(headerVariable);

StreamResult(bodyVariable);

// Stream header or body in several parts, using several

// method calls, starting with the header

StreamResultHeader(startHeader);

StreamResultHeader(finishHeader);

StreamResult(bodyStart);

StreamResult(bodyMiddle);

StreamResult(bodyEnd);