| Previous Contents Index DocHome Next |
| iPlanet Application Server Java Foundation Class Reference |
Chapter 3 Interfaces
This chapter provides reference material on the interfaces in the iPlanet Application Server Foundation Class Library.The following interfaces are described in this chapter:
This interface extends the standard javax.servlet.http.HttpServletRequest interface.
Although anyone developing an application for iPlanet Application Server can use HttpServletRequest2, this interface is typically used in components generated by iplanet Application Builder. HttpServletRequest2 provides methods for handling servlet errors, as well as providing additional support for servlets.
One method in particular, the getAppLogic( ) method, is useful to developers outside the iAB environment. Through the getAppLogic( ) method, the HttpServletRequest2 interface supports servlet access to AppLogics, allowing applications to call methods on AppLogics.
Package
com.netscape.server.servlet.extension
Related Topics
IServletErrorHandler Interface
convertITemplateDataToResultSet( )
Creates a ResultSet wrapper for an ITemplateData object.
Syntax
public static ResultSet convertITemplateDataToResultSet(
String groupName,
ITemplateData templateData)groupName. The group name of the specified ITemplateData.
templateData. The ITemplateData to be wrapped.
Usage
The convertITemplateDataToResultSet( ) method takes an ITemplateData object and wraps it so that it conforms to the specifications of a JDBC ResultSet object.Use this method only if you have HTML templates that were developed for a previous version of iAS, and you want to run them in the JSP engine.
Rules
Hierarchical ITemplateData objects are not supported, so do not specify one as a parameter.
Return Value
A ResultSet object.
Calls a method corresponding to a form-action in a servlet.
Syntax
public abstract int dispatchAction(
HttpServletResponse response,
HttpServlet servlet) throws ServletException, IOExceptionresponse. The HttpServletResponse object.
servlet. The HttpServlet object on which the actionHandler will be invoked.
Usage
Use this method to handle form actions. For example, if an application user presses a button in a web page form, the dispatchAction( ) method calls the button handler method that corresponds to the specific form and action.The form, action, and corresponding handler are defined by the servlet developer in the servlet's NTV file.
Tip
It is useful to call formActionHandlerExists( ) before dispatchAction( ) to determine whether the servlet has form-actions defined on it.
Return Value
Returns NO_ERROR (a value of 0) if the method succeeds; otherwise, returns ERROR_NO_DISPATCH_HANDLER. (a value of 1), which means that dispatching cannot be done. If an event handler exists and is called, then dispatchAction( ) returns that handler's return value.
Related Topics
formActionHandlerExists( )
Determines whether the servlet has form-actions defined on it.
Syntax
public abstract boolean formActionHandlerExists()
Usage
This method accesses the NTV list and, by doing so, determines whether the servlet has form-actions defined on it. This information is useful to the dispatchAction( ) method, so you typically call formActionHandlerExists( ) before dispatchAction( ).
Tip
This method appears in code generated by iPlanet Application Builder. If you are not using iAB, you typically will not need to call this method.
Return Value
Returns true if form-actions are defined on the servlet.
Related Topics
dispatchAction( )
Returns a handle to the AppLogic instance (ServletRunner) that served this request.
Syntax
public abstract AppLogic getAppLogic()
Usage
Use this method when you want to access the ServletRunner AppLogic. The getAppLogic( ) method lets developers call any AppLogic methods.
Tip
Deprecated AppLogic methods should not be called. For example, calling methods that stream data, such as streamResult( ), streamResultBinary( ), and streamResultHeader( ), may conflict with similar methods in HTTPResponse that also stream data.
Return Value
An AppLogic object.
Retrieves the name of the file that handles output.
Syntax
public abstract String getDefaultTemplate()
Usage
In some cases, a servlet's NTV file indicates a default servlet or JSP file that handles output. If so, calling getDefaultTemplate( ) retrieves this NTV setting.
Tip
This method appears in code generated by iPlanet Application Builder. If you are not using iAB, you typically will not need to call this method.
Return Value
A String value representing the name of the default template.
Related Topics
setDefaultTemplate( )
Retrieves a vector of error codes.
Syntax
public abstract Vector getErrorCodes()
Return Value
A vector of error codes that correspond to the input variables that failed validation. A code is associated with each type of data validated, as summarized in the following table:
Retrieves a vector of error messages.
Syntax
public abstract Vector getErrorMsgs()
Return Value
A vector of error messages that correspond to the input variables that failed validation. A message is associated with each type of data validated, as summarized in the following table:
Retrieves a vector of input variables.
Syntax
public abstract Vector getErrorVars()
Return Value
A vector of the names of input variables that failed to validate.
Retrieves an instance of a session object that is defined by the programmer.
Syntax 1
Use this syntax in most situations.public abstract HttpSession getHttpSessionBean()
Syntax 2
Use this syntax to explicitly indicate whether to create the session or not.public abstract HttpSession getHttpSessionBean(
boolean create)create. Supply a value of true if the session is to be created; otherwise, specify false.
Usage
The getHttpSessionBean( ) method retrieves the HttpSession or HttpSession2 object that is an instance of the class designated by the httpSessionBeanClass setting. This setting is defined in the SessionInfo section of an application's appInfo.ntv file. This setting allows application developers to provide bean-like HttpSession implementations.
Tip
This method appears in code generated by iPlanet Application Builder. If you are not using iAB, you typically will not need to call this method.
Return Value
An HttpSession or HttpSession2 object representing an instance of the class designated by httpSessionBeanClass.
Related Topics
getSession( ) in the javax.servlet.http.HttpServletRequest interface
Retrieves the object that handles validation errors.
Syntax
public abstract IServletErrorHandler getServletErrorHandler()
Usage
This method is used to retrieve the IServletErrorHandler object that handles errors that occur during validation. You can retrieve the object elsewhere if you need to call the included functionality.
Tip
This method appears in code generated by iPlanet Application Builder. If you are not using iAB, you typically will not need to call this method.
Return Value
The IServletErrorHandler object.
Related Topics
IServletErrorHandler interface
Sets the default template to another file.
Syntax
public abstract void setDefaultTemplate(
String template)template. The new name of the default template; the name applies only for this invocation of the servlet.
Usage
The default template is defined in a servlet's NTV file. However, in some cases it's useful to reset the default template to another file. To do so, call setDefaultTemplate( ). To retrieve the name of the current default template, call getDefaultTemplate( ).
Tip
This method appears in code generated by iPlanet Application Builder. If you are not using iAB6.0, you typically will not need to call this method.
Related Topics
getDefaultTemplate( )
Sets the IServletErrorHandler that is used to process errors.
Syntax
public abstract void setServletErrorHandler(
IServletErrorHandler handler)handler. The error handler to be set.
Usage
A servlet error handler is always set on a request object by default. However, you may want to implement your own, so the setServletErrorHandler( ) method is provided to allow that.This method sets the IServletErrorHandler that is used to process errors that happen during validation (and possibly elsewhere). To retrieve the IServletErrorHandler, call getServletErrorHandler( ).
Tip
This method appears in code generated by iPlanet Application Builder. If you are not using iAB, you typically will not need to call this method.
Related Topics
getServletErrorHandler( )
Validates input parameters and session variables.
Syntax 1
Use this version to validate all input parameters and session variables listed in the servlet's NTV file. This version also streams out an error on failure.public abstract boolean validate(
HttpServletResponse response)
throws ServletException, IOException
Syntax 2
Use this version to validate specific input parameters and session variables (or those listed in the servlet's NTV file). This version also streams out an error on failure.public abstract boolean validate(
String params[],
String sessionVars[],
HttpServletResponse response)
throws ServletException, IOException
Syntax 3
Use this version to validate specific input parameters and session variables (or those listed in the servlet's NTV file). No error streaming occurs.public abstract boolean validate(
String params[],
String sessionVars[])
Syntax 4
Use this version to validate all input parameters and session variables listed in the servlet's NTV file. No error streaming occurs.public abstract boolean validate()
response. The HttpServletResponse object.
params. The array of parameters to validate. Specify NULL to validate all input parameters listed in the NTV file.
sessionVars. The array of session variables to validate. Specify NULL to validate all session variables listed in the NTV file.
Usage
Use this method whenever you want to validate parameters. There are four ways to invoke the validate( ) method. One version validates all input and session variables listed in a servlet's NTV file. Another version validates a specified array of input parameters or session variables. For each of these two versions, you can either ignore failure conditions or stream an error on failure.When validate( ) is called and a validation error is detected, validate( ) then calls either of two IServletErrorHandler methods: handleInputValueError( ) or handleSessionVariableError( ). The previous two methods might return a positive number, meaning that a real error occurred and is queued into the error-specific vectors. If this happens, then streamError( ) is called once before validate( ) returns (assuming the validate( ) call is one of the two variants that streams errors).
The validate( ) method passes in one of the following error types as input to the two error handler methods, handleInputValueError( ) or handleSessionVariableError( ):
Return Value
Returns true if the validation was successful; otherwise, returns false.
Related Topics
IServletErrorHandler interface
The HttpSession2 interface is used within JSPs and servlets to share session state with AppLogics.
iPlanet Application Server already supports javax.servlet.http.HttpSession as a standard interface to iPlanet Application Server sessions. But the application server also provides HttpSession2, a iAS-specific interface. HttpSession2 gives servlets direct access to iPlanet Application Server sessions. Therefore, servlet programmers can use HttpSession2 to share sessions between AppLogics and servlets.
Sharing sessions is useful when you want to migrate an application from iPlanet Application Server 2.x to iPlanet Application Server 6.0. When migrating an application, one of the tasks is to rewrite AppLogics into servlets. Furthermore, when you rewrite AppLogics, you typically need to use iAS-specific servlet interfaces, such as HttpSession2 and HttpServletRequest2. The resulting servlet is nonstandard; however, the alternate approach—mixing AppLogics and standard servlets—is not recommended.
In servlets, a session is an instance of HttpSession. But in AppLogics, session data is an IValList object. An AppLogic stores integers, strings, and blobs (byte arrays) in a session, whereas a servlet stores serializable objects in a session. As a result, there is no immediate mapping between what an AppLogic stores and and what a servlet stores in a session (except for strings).
The HttpSession2 interface solves the issue of sharing session data. HttpSession2 provides methods for storing and retrieving integers, strings, blobs, and user login data—methods that parallel what an AppLogic developer uses. In this way, HttpSession2 enables sessions to work back and forth across AppLogics and servlets.
HttpSession2 provides loginSession( ) and logoutSession( ) for servlets to share the AppLogic session API. These two methods are typically used with isAuthorized( ), as is done for AppLogics. Servlets are also registered with an access control list, so that a secure session established in an AppLogic can be used in a servlet, and vice versa.
Package
com.netscape.server.servlet.extension
Returns the byte array defined by the specified name in the session.
Syntax
public abstract byte[] getBytes(
String name)name. The name whose value is to be returned.
Return Value
The byte array defined by name in the session, or null if name is not defined.
Returns the integer defined by the specified name in the session.
Syntax
public abstract int getInt(
String name)name. The name whose value is to be returned.
Return Value
The integer defined by name in the session, or -1 if name is not defined.
Returns the string defined by the specified name in the session.
Syntax
public abstract String getString(
String name)name. The name whose value is to be returned.
Return Value
The string defined by name in the session, or null if name is not defined.
Checks whether the current user has a specified permission.
Syntax
public abstract boolean isAuthorized(
String acl,
String permission)acl. The access control list in which to check for the permission.
permission. The permission to check for.
Usage
Use isAuthorized( ) in portions of the code where application security is enforced through Access Control Lists (ACLs). This method lets an application check a specified ACL to determine whether a user has permission to execute a servlet (or AppLogic) or to perform a particular action. The application can use the result of isAuthorized( ) as a condition in an If statement. It can, for example, return a message to users who are denied access to a servlet (or AppLogic).Each ACL is defined in the registry and maps users to privileges such as read and write. Application developers should obtain the list of registered ACLs, users and groups from the server administrator who created these items. ACLs are created through the Enterprise Administrator tool or through the kreg tool.
Rule
Before calling isAuthorized( ), the application must create a session. The user must also be logged in with loginSession( ).
Return Value
Returns true if the authorization check succeeds; otherwise, returns false.
Related Topics
loginSession( )
Logs an authorized user into a session with a secured application.
Syntax
public abstract boolean loginSession(
String user,
String password)
Usage
The loginSession( ) method logs the named user in the session, using the given password. Logging in associates the user with the session so that the application can control authorization of AppLogic and servlet access.Call loginSession( ) after creating or retrieving a user session. loginSession( ) checks the passed in login name and password against the user names and passwords stored in the iPlanet Application Server (the administrator sets up and manages this information) and logs the user into the session if the login name and password are valid.
If login is successful, a security credential object is created and associated with the session. The server checks this security credential object each time it receives an AppLogic or servlet request, and verifies if the user has execute permission for the AppLogic or servlet.
Using loginSession( ) in conjunction with isAuthorized( ), an application can ensure that only authorized users can take certain actions, such as executing AppLogics or servlets.
Tip
The server administrator creates users and passwords and manages access to AppLogics, servlets, and specified resources, such as sales or forecast reports. During the development and debugging phases, application developers can use the ldapmodify tool to create users, groups, and ACLs in the LDIF file. These tasks cannot be done programmatically.
Return Value
Returns true if the login is successful.
Related Topics
isAuthorized( ), logoutSession( )
Removes a user's association with a session.
Syntax
public abstract int logoutSession()
Usage
AppLogics or servlets call loginSession( ) to log into a session with a secured application. If loginSession( ) was called, you must call logoutSession( ) when the user exits the application or the secured portion of it.
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
isAuthorized( ), loginSession( )
Defines a name in the session to have a specified byte array value.
Syntax
public abstract void putBytes(
String name,
byte[] value)
value. The byte array value to assign to name.
Defines a name in the session to have a specified integer value.
Syntax
public abstract void putInt(
String name,
int value)
value. The integer value to assign to name.
Defines a name in the session to have a specified String value.
Syntax
public abstract void putString(
String name,
String value)
value. The String value to assign to name.
IAppEvent Interface (deprecated)
IAppEvent is deprecated and is provided for backward compatibility only. New applications should use the iPlanet Application Server API's two replacement interfaces: IAppEventMgr and IAppEventObj.
The IAppEvent interface represents the defined events an application supports. An AppLogic can define events that are triggered at a specified time or times or when triggered explicitly.
Currently, an AppLogic can execute two actions when an event is triggered:
Events are stored persistently in the iPlanet Application Server, and are removed only when your application explicitly deletes them. They are typically used to schedule routine administrative tasks, such as making back-ups or getting statistics.
The IAppEvent interface defines methods for registering, triggering, enabling, disabling and deleting events. To create an instance of the IAppEvent interface, use the getAppEvent( ) method in the AppLogic class.
Example
The following example shows AppLogic code that registers two application events:
The first event runs the RepGenAgent AppLogic at 5 AM everyday
The second event emails a report generated by RepGenAgent at 6 AM everyday
Related Topics
getAppEvent( ) method in the AppLogic classIAppEvent Interface (deprecated)
Removes a registered event from the iPlanet Application Server.
Syntax
public int deleteEvent(
String pEventName)pEventName. The name of the registered event to delete.
Usage
Use deleteEvent( ) to remove an event that is no longer required. To temporarily stop a event from being triggered, use disableEvent( ).
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
disableEvent( )
Syntax
public int disableEvent(
String pEventName)pEventName. The name of the registered event to disable.
Usage
Use disableEvent( ) to temporarily stop an event from being triggered. The event is disabled until it is enabled with enableEvent( ). To remove an event from the iPlanet Application Server permanently, use deleteEvent( ).
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
deleteEvent( )
Syntax
public int enableEvent(
String pEventName)pEventName. The name of the registered event to enable.
Usage
Use enableEvent( ) to prepare a specified event for activation. Call enableEvent( ) after you register an event with registerEvent( ), or to enable a trigger that was disabled with disableEvent( ).
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
disableEvent( )
Returns the list of registered events.
Syntax
public IEnumObject enumEvent()
Usage
Use enumEvents( ) to get information on all the registered events. The IEnumObject object returned by enumEvents( ) contains a set of IValList objects, one per event. Each IValList contains the properties assigned to the event when it was registered with registerEvent( ).
Tip
Use the methods in the IEnumObject interface to iterate through the contents of the returned IEnumObject object.
Example
The following AppLogic code shows how to use enumEvents( ) to get information on all the registered events and save it to a report:
Return Value
IEnumObject that contains the list of events, or null for failure.
Related Topics
getAppEvent( ) method in the AppLogic class
Returns the properties of a registered event.
Syntax
public IValList queryEvent(
String pEventName)pEventName. The name of the registered event to enable.
Usage
When an AppLogic calls registerEvent( ), it can specify any of the following:
The initial state—enable or disabled—of the event
Use queryEvent( ) to get the properties that were specified for a specific event.The time the event is to be triggered
Return Value
IValList object that contains information about the event.
Related Topics
registerEvent( )
Registers a named event for use in applications.
Syntax
public int registerEvent(
String pEventName,
IValList pValList)pEventName. The name of the event to register.
pValList. The IValList object that specifies the properties of the event. The following table lists the keys and values you can specify:
* You must specify all of these items if sending email when the event is triggered.
Usage
Use registerEvent( ) to define each event your application will use. You can specify that a triggered event sends an email, or runs an AppLogic, or both.
Return Value
GXE.SUCCESS if the method succeeds.
Example
The following example shows how to define and register an application event:
Related Topics
enableEvent( )getAppEvent( ) method in the AppLogic class
Syntax
public int setEvent(
String pEventName,
int dwOverrideFlag,
IValList pValList)pEventName. The name of the event to trigger.
dwOverrideFlag. Specify 0 (zero) to trigger the event with the previously specified actions. To override the defined actions, you can specify the following:
GX_AE_SE_OR_FLAG.GX_AE_SE_ACTION_NOMAIL if you don't want to send email when the event is triggered.
GX_AE_SE_OR_FLAG.GX_AE_SE_ACTION_NOREQ if you don't want to run an AppLogic when the event is triggered.
pValList. The IValList object that specifies the event properties you want to override. Specify null to use the properties already defined for the event. The following table lists the keys and values you can specify:
* You must specify all of these items if sending email when the event is triggered.
Usage
Use setEvent( ) to trigger a registered event immediately. This is useful for testing purposes.
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
registerEvent( )getAppEvent( ) method in the AppLogic class
Application components can define events that are either triggered at a specified time or triggered explicitly. Events are stored persistently in the iPlanet Application Server, and are removed only when your application explicitly deletes them. Events are typically used to schedule routine administrative tasks, such as making back-ups or getting statistics.
iPlanet Application Server uses two new interfaces to support events:
The IAppEventMgr interface manages application events. This interface defines methods for creating, registering, triggering, enabling, disabling, enumerating, and deleting events.
IAppEventMgr and IAppEventObj should be used in new or migrated applications. Existing iPlanet Application Server applications can continue using the deprecated IAppEvent interface, which supports the previous model for application events.The IAppEventObj interface represents the defined events an application supports. This interface defines methods not only for getting or setting attributes of an event, but also for adding, deleting, or enumerating actions of the event.
Attributes and Actions
For each event, you define associated attributes and actions. Attributes determine the following characteristics:
the event's state (enabled or disabled)
When an event is triggered, it performs one or more of the following types of actions:the execution mode (concurrent or serial) of the event's actions
Features of Application Event Support
Support for application events includes the following:
Added functionality
Execution of multiple actions of any type. (IAppEvent supports only one action of each type.)
Different interfacesIn addition to executing an AppLogic and sending email, a triggered event can now execute a servlet as one of the supported action types.
Synchronous or asynchronous triggering of events. (IAppEvent supports only synchronous triggering.)
Execution of actions in the same order they are registered.
Execution of actions either concurrently or serially.
Support for passing an input IValList object to triggered events.
Separate actions and attributes
- Previously, application events were represented by an IValList object, and you used the IAppEvent interface to manage the events. Now an application event is represented by an IAppEventObj, and you use IAppEventMgr to manage and control the events.
- Previously, attributes and actions were not distinguished. They were all treated as event properties and specified within a single IValList object. Now attributes are described by entries in one IValList object, and each action is represented by its own additional IValList object.
- IAppEventObj has methods for getting or setting attributes and for adding, deleting, or enumerating actions.
Accessing and Creating Application Events
To access an IAppEventMgr object, use the GetAppEventMgr( ) method in the GXContext class:IAppEventMgr com.kivasoft.dlm.GXContext.GetAppEventMgr(
IContext context);The context parameter is an IContext object, which provides access to iPlanet Application Server services. For information about obtaining this IContext object, see the GXContext class or the IContext Interface.
After creating the IAppEventMgr object, you can create an application event (an instance of IAppEventObj) by calling createEvent( ) on the IAppEventMgr object.
Registering Events
After creating an application event, you can set its attributes and add actions using methods on the IAppEventObj. Then, register the application event by calling registerEvent( ) on the manager object.
Related Topics
GetAppEventMgr( ) in the GXContext class,
IValList Interface (deprecated),
IAppEvent Interface (deprecated)
Creates an empty application event object.
Syntax
public IAppEventObj createEvent(
String pEventName)pEventName. The name of the event to create.
Usage
Use createEvent( ) to create an empty IAppEventObj object. You can use methods of the IAppEventObj interface to set attributes and actions on the returned object.Changes to the event object do not take effect until it is registered with the manager object, through a call to registerEvent( ).
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
queryEvent( )
Removes a registered event from iPlanet Application Server.
Syntax
public int deleteEvent(
String pEventName)pEventName. The name of the registered event to delete.
Usage
Use deleteEvent( ) to remove an event that is no longer required. The specified event is removed from iAS.To temporarily stop an event from being triggered, use disableEvent( ).
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
disableEvent( )
Syntax
public int disableEvent(
String pEventName)pEventName. The name of the registered event to disable.
Usage
Use disableEvent( ) to temporarily stop an event from being triggered. The event is disabled until it is enabled with enableEvent( ). To permanently remove an event from the registry, use deleteEvent( ).
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
deleteEvent( )
Syntax
public int enableEvent(
String pEventName)pEventName. The name of the registered event to enable.
Usage
Use enableEvent( ) to enable an event. A given event could have been disabled in either of two ways: by a previous call to disableEvent( ) or by initially registering the event using a disabled state attribute.
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
disableEvent( )
Enumerates through the list of registered events.
Syntax
public IEnumObject enumEvents()
Usage
Use enumEvents( ) to get information on all the registered events. The IEnumObject object returned by enumEvents( ) contains a set of IAppEventObj objects, one per event. Each IAppEventObj contains the attributes and actions that were assigned to the event when it was registered with registerEvent( ).
Tip
Use the methods in the IEnumObject interface to iterate through the contents of the returned IEnumObject object.
Example
The following AppLogic code shows how to use enumEvents( ) to get information on all the registered events and save it to a report:
Return Value
IEnumObject that contains the list of events, or null for failure.
Related Topics
IEnumObject interface
Retrieves the IAppEventObj for a registered event.
Syntax
public IAppEventObj getEvent(
String pEventName)pEventName. The name of the registered event.
Usage
After calling getEvent( ), you can call methods on the returned IAppEventObj. For example, you can query the object by calling getAttributes( ) or enumActions( ), or you can modify the object by calling setAttributes( ).
Return Value
IAppEventObj for the specified event.
Related Topics
registerEvent( )
Registers a named event for use in applications.
Syntax
public int registerEvent(
IAppEventObj appEventObj)appEventObj. The event object whose attributes and actions have been set.
Usage
After an application event object is created with createEvent( ), you define its attributes and actions using methods of the IAppEventObj interface. Then you use registerEvent( ) to register the specified event object. Registration commits the changed attributes and actions to the server and to the registry. If an event object already exists for the given name, the existing object is deleted and replaced with the specified object.
Return Value
GXE.SUCCESS if the method succeeds.
Example
The following example shows how to define and register an application event:
Related Topics
enableEvent( )
Syntax
public int triggerEvent(
String pEventName,
IValList pValList,
boolean syncFlag)pEventName. The name of the event to trigger.
pValList. The IValList object that specifies the input that is passed to the triggered event and its actions.
syncFlag. The boolean flag that indicates whether the event is to be triggered synchronously (value is true) or asynchronously (value is false).
Usage
Use triggerEvent( ) to trigger a registered event. When you specify the pValList parameter, a copy of this IValList object is passed as input to all actions registered with the application event.
If the action is ...
Then pValList is ...
passed to the servlet as the valIn of the underlying AppLogic.
Use the syncFlag parameter to determine synchronous or asynchrous execution. Typical usage is to set syncFlag to false, which provides asynchronous execution and better application performance. When syncFlag is false, the event is triggered, and the method call returns immediately, without waiting for the actions to finish executing.
If syncFlag is true, then the method call does not return immediately. Instead, the call blocks until the event is triggered and all actions have executed. In some cases, it may be desirable for actions to finish executing before returning control to the application.
Actions are triggered in the same order in which they were added to the application event object.
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
registerEvent( )
See the IAppEventMgr interface for details on IAppEventObj.
Related Topics
IAppEventMgr interface
Appends an action to an ordered list of actions.
Syntax
public int addAction(
IValList action)action. The input IValList object that defines the action to add. When an event is triggered, actions are executed in the same order in which they were added. The entries in this IValList object vary from one action type to another.
The keys and values you can specify are as follows. Note that string constants are available in the class com.kivasoft.types.GXConstants.
To send email when the event is triggered, all of the following items must be specified.
Key
Value
The name of the file that contains the body of an email message.
Usage
Use the addAction( ) method after creating an application event object (by calling createEvent( ) on the IAppEventMgr object). After you change an event (for example, by adding or deleting actions or by setting attributes), you must register the event in order for the changes to take effect.To list the added actions, use enumActions( ). To delete all actions, use deleteActions( ).
Return Value
GXE.SUCCESS if the method succeeds.
Deletes all actions added to this IAppEventObj.
Syntax
public int deleteActions()
Usage
Use this method to remove all actions associated with this IAppEventObj.
Return Value
GXE.SUCCESS if the method succeeds.
Enumerates the actions added to this IAppEventObj.
Syntax
public IEnumObject enumActions()
Usage
Use this method to obtain a list of actions that have been added to this IAppEventObj. Each entry in the returned IEnumObject is an IValList object representing an action.
Return Value
IEnumObject that contains the list of actions, or null for failure.
Retrieves the list of attributes of an IAppEventObj.
Syntax
public IValList getAttributes()
Usage
Call this method after calling setAttributes( ).
Return Value
IValList object that contains the list of attributes, or null for failure.
Related Topics
setAttributes( )
Retrieves the name of the IAppEventObj.
Syntax
public String getName()pName. A pointer to an input buffer.
nName. The size of the input buffer.
Usage
The name of an IAppEventObj is set by calling createEvent( ) on the IAppEventMgr object. After creating an application event object, use the getName( ) method to retrieve the name.
Return Value
A string representing the name of the application event object, or null for failure.
Sets a list of attribute values for the IAppEventObj.
Syntax
public int setAttributes(
IValList attrList)attrList. The input IValList object that specifies the attributes. The keys and values you can specify are as follows. Note that string constants are available in the class com.kivasoft.types.GXConstants.
GXConstants.GX_AE2_RE_KEY_STATE
GXConstants.GX_AE2_RE_KEY_TIME
- A variable that specifies the initial state of the event. This key is optional and has the following possible values:
- An optional key that specifies the time at which the event will be triggered. Use the following format:
GXConstants.GX_AE2_RE_KEY_ACTION_MODE
- Each of these fields may be either an asterisk (meaning all legal values) or a list of elements separated by commas. An element is either a number or two numbers separated by a minus sign indicating an inclusive range. For example, 2, 5 - 7:0:0 5/*/* means the event is triggered at 2 AM, 5AM, 6 AM and 7 AM every Friday.
- The specification of days can be made by two fields: day of the month (DD) and day of the week (W). If both are specified, both take effect. For example, 1:0:0 1/15/* means the event is triggered at 1 AM every Monday, as well as on the fifteenth of each month. To specify days by only one field, set the other field to *.
- An optional key that specifies whether actions are to be executed concurrently (at the same time) or in series (one after another). In serial execution, each action finishes executing before the next one starts, and execution occurs in the same order in which the actions were added.
- This key has the following possible values:
Usage
Use the setAttributes( ) method after creating an application event object (by calling createEvent( ) on the IAppEventMgr object). After you change an event (for example, by adding or deleting actions or by changing attributes), you must register the event in order for the changes to take effect.
Tip
None of the attributes are required to be set. The default state is enabled, and the default action mode is concurrent.To retrieve the list of attributes that are set, use getAttributes( ).
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
getAttributes( )
IBuffer Interface (deprecated)
The IBuffer interface is deprecated and is provided for backward compatibility only. New applications developed according to the servlet-JSP programming model do not need the functionality provided by IBuffer.
The IBuffer interface represents a block of memory. Input arguments and output value(s) of methods are sometimes stored in IBuffer objects. For example, the get**( ) methods in the IQuery interface return values in an IBuffer object.
IBuffer provides methods for specifying and obtaining the size of the memory block, obtaining its starting address, and copying data to it.
To create an instance of the IBuffer interface, use the GX.CreateBuffer( ) method. To create and initialize an IBuffer object with string contents, use GX.CreateBufferFromString( ).
Specifies the size of the memory block, in bytes.
Syntax
public int alloc(
int nSize)nSize. Size of the memory block, in bytes.
Usage
After creating a memory buffer with the GX.CreateBuffer( ) function, use alloc( ) to specify its size.Subsequent calls to getSize( ) return the size that AppLogic specified when it called alloc( ).
If the AppLogic creates its own new IBuffer object, it must first specify the size of the memory block by calling alloc( ) before using other methods in the interface.
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
getAddress( )
Returns a copy of the buffer contents.
Syntax
public byte[] getAddress()
Usage
Use getAddress( ) to get a copy of the contents in a buffer.
Return Value
A copy of the buffer contents.
Related Topics
alloc( )
Returns the size of the memory block, in bytes.
Usage
Use getSize( ) to determine the length of the memory buffer that the AppLogic specified when it called alloc( ).
Rule
Before calling getSize( ), AppLogic must first specify the size of the memory block by calling alloc( ).
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
getAddress( )
Copies data to a memory block.
Syntax
public int setData(
byte[] pData,
int nDataLen)pData. The data to copy to the memory buffer.
nDataLen. The length, in bytes, of the data to copy to the memory buffer.
Usage
Use setData( ) to copy data to a memory buffer. The buffer can then be passed to a method, such as the setValPieceByOrd( ) method in the ITable interface, that accepts data values in a buffer object.
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
getAddress( )
ICallableStmt Interface (deprecated)
ICallableStmt is deprecated and is provided for backward compatibility only. New applications should use the java.sql.ICallableStatement interface from the JDBC Core API.
The ICallableStmt interface provides a standard way to call stored procedures in any database server. A stored procedure is a block of SQL statements stored in a database. Stored procedures provide centralized code for manipulating data and reduce the amount of data that needs to be sent to the client side of an application. They are typically used to execute database operations, for example, modify, insert, or delete records.
To call a stored procedure from an AppLogic, use the ICallableStmt object. The ICallableStmt interface defines methods for executing a stored procedure or function, and setting and getting parameter values to and from a stored procedure.
To create an instance of the ICallableStmt interface, use prepareCall( ) in the IDataConn interface.
Related Topics
prepareCall( ) in the IDataConn Interface (deprecated)
Releases the callable statement.
Usage
Use close( ) to release a callable statement object after the AppLogic has finished processing the results returned by the stored procedure. You must release the callable statement object so that the data connection is available to process other commands.
Return Value
GXE.SUCCESS if the method succeeds.
Executes the stored procedure called by the ICallableStmt object.
Syntax
public IResultSet execute(
int flags,
IValList params,
ITrans trans,
IValList props);
For synchronous operations, the default, specify 0 (zero) or GX_DA_EXECUTEQUERY_FLAGS.GX_DA_EXEC_SYNC.
For asynchronous operations, specify GX_DA_EXECUTEQUERY_FLAGS.GX_DA_EXEC_ASYNC.
params . IValList object that contains parameters to pass to the callable statement. If you use setParams( ) instead to specify the parameters, specify null here.
trans . ITrans object that contains the transaction associated with this callable statement, or null for no transaction.
props . IValList object that contains properties, or null for no properties. This parameter applies only if the callable statement returns a result set. Informix stored procedures, for example, return out parameter values only as a result set. Sybase, DB2, and MS SQL Server stored procedures also support the return of a result set. Multiple result sets, however, is not supported.
After instantiating an object of the IValList interface, set any of the following properties:
RS_BUFFERING turns on result set buffering when set to "TRUE" or "YES."
If RS_BUFFERING is enabled and if the optional parameters are not specified, the global values in the registry are used instead.RS_INIT_ROWS specifies the initial size of the buffer, in number of rows. If the result set size exceeds this setting, a fetchNext( ) call will return the error GX_DA_FETCHNEXT_RESULTS.GX_DA_BUFFER_EXCEEDED and result set buffering will be turned off.
RS_MAX_ROWS specifies the maximum number of rows for the buffer. If the result set size exceeds this setting, a fetchNext( ) call will return the error GX_DA_FETCHNEXT_RESULTS.GX_DA_BUFFER_EXCEEDED and result set buffering will be turned off.
RS_MAX_SIZE specifies the maximum number of bytes for the buffer.
Usage
Use execute( ) to run a callable statement that has been created with prepareCall( ) in the IDataConn interface. If the stored procedure called by the ICallableStmt object can return multiple result sets, use executeMultipleRS( ) instead.If the stored procedure called by the ICallableStmt object contains parameters, instantiate an IValList object and use setValString( ) or setValInt( ) in the IValList interface to specify the parameter values to pass to the stored procedure.
After creating and setting up the IValList object, pass it to execute( ) or setParams. If you use setParams( ) to pass parameters to the stored procedure, specify NULL for the params parameter in execute( ).
Rule
When accessing a stored procedure on Sybase or MS SQL Server, input parameter names specified in the call must be prefixed with the ampersand (&) character, for example, ¶m1. Other database drivers accept the ampersand, as well, as the colon (:) character. For all database drivers, input/output and output parameter names are prefixed with the colon (:) character, for example, :param2.
Return Value
IResultSet object, or null for failure (such as an invalid parameter).
Related Topics
prepareCall( ) in the IDataConn Interface (deprecated)
Executes a stored procedure, called by the ICallableStmt object, that can return multiple result sets.
Syntax
public int executeMultipleRS(
int dwFlags,
IValList pParams,
ITrans pTrans,
IValList pProps);
pParams. IValList object that contains parameters to pass to the callable statement. If no parameters are required, pass in an empty IValList. If you use setParams( ) instead to specify the parameters, specify null here.
pTrans. ITrans object that contains the transaction associated with this callable statement, or null for no transaction.
pProps. IValList object that contains properties, or null for no properties.
After instantiating an object of the IValList interface, set any of the following properties:
RS_BUFFERING turns on result set buffering when set to "TRUE" or "YES."
If RS_BUFFERING is enabled and if the optional parameters are not specified, the global values in the registry are used instead.RS_INIT_ROWS specifies the initial size of the buffer, in number of rows. If the result set size exceeds this setting, a fetchNext( ) call will return the error GX_DA_FETCHNEXT_RESULTS.GX_DA_BUFFER_EXCEEDED and result set buffering will be turned off.
RS_MAX_ROWS specifies the maximum number of rows for the buffer. If the result set size exceeds this setting, a fetchNext( ) call will return the error GX_DA_FETCHNEXT_RESULTS.GX_DA_BUFFER_EXCEEDED and result set buffering will be turned off.
RS_MAX_SIZE specifies the maximum number of bytes for the buffer.
Usage
Use executeMultipleRS( ) to run a callable statement that returns multiple result sets. The callable statement should already have been created with prepareCall( ) in the IDataConn interface.If the stored procedure called by the ICallableStmt object contains parameters, instantiate an IValList object and use setValString( ) or setValInt( ) in the IValList interface to specify the parameter values to pass to the stored procedure.
After creating and setting up the IValList object, pass it to executeMultipleRS( ) or setParams. If you use setParams( ) to pass parameters to the stored procedure, specify NULL for the pParams parameter in executeMultipleRS( ).
Rule
When accessing a stored procedure on Sybase or MS SQL Server, input parameter names specified in the call must be prefixed with the ampersand (&) character, for example, ¶m1. Other database drivers accept the ampersand, as well, as the colon (:) character. For all database drivers, input/output and output parameter names are prefixed with the colon (:) character, for example, :param2.
Tip
The difference between execute( ) and executeMultipleRS( ) is that execute( ) can return only a single result set. If you're not sure how many results sets, if any, a stored procedure returns, use executeMultipleRS( ).
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
prepareCall( ) in the IDataConn Interface (deprecated)
Checks if there is a result set to retrieve. This method is valid only if you used executeMultipleRS( ) (instead of execute( )) to execute a stored procedure called by the ICallableStmt object.
Syntax
public boolean getMoreResults()
Usage
If you used executeMultipleRS( ) to execute a stored procedure that returns multiple results sets, use getMoreResults( ) in conjunction with getResultSet( ) to check if there is a result set before retrieving it.If there is a current result set with unretrieved rows, getMoreResults( ) discards the current result set and makes the next result set available.
Return Value
True if there is a result set.
Related Topics
prepareCall( ) in the IDataConn Interface (deprecated)
Returns the value of the stored procedure's output parameter or parameters.
Syntax
public IValList getParams(
int dwFlags);
Usage
Some stored procedures return output parameters. If the stored procedure your callable statement executes returns output parameters, use getParams( ) to get the values.The getParams( ) method returns the values in an IValList object. The key names associated with the values are the parameter names as specified in the query that was passed to the prepareCall( ) method
Tip
Informix stored procedures return output parameters in a result set. This result set is returned by execute( ) or executeMultipleRS( ). The getParams( ) method, therefore, does not apply to Informix stored procedures.
Return Value
IValList object, or null for failure.
Related Topics
prepareCall( ) in the IDataConn Interface (deprecated)
Retrieves a result set. This method is valid only if you used executeMultipleRS( ) (instead of execute( )) to execute a stored procedure called by the ICallableStmt object.
Syntax
public IResultSet getResultSet()
Usage
If you used executeMultipleRS( ) to execute a stored procedure that returns multiple results sets, use getResultSet( ) in conjunction with getMoreResults( ) to retrieve the results sets.
Return Value
IResultSet object, or null if there is no result set.
Related Topics
prepareCall( ) in the IDataConn Interface (deprecated)
Specifies the parameter values to pass to the stored procedure.
Syntax
public int setParams(
int dwFlags,
IValList pParams);dwFlags. Specify 0 (zero). For internal use only.
pParams. IValList object that contains the parameters to pass to the stored procedure. You must set all parameters required by the stored procedure. If you don't, a runtime error will occur when execute( ) is called. If you use setParams( ), specify NULL for the pParams parameter in execute( ).
Usage
If the stored procedure the callable statement executes accepts input parameters, use setParams( ) to pass the parameter or parameter values. The alternative is to pass the parameter values with the execute( ) method. Parameters passed to execute( ) supersede parameters specified with setParams( ).For both setParams( ) and execute( ), you pass the parameter values in an IValList object.
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
prepareCall( ) in the IDataConn Interface (deprecated)
The ICallerContext interface manages programmatic security from within a servlet. ICallerContext provides two methods that override equivalent methods in the standard javax.ejb.EJBContext interface.
From within EJBs, do not use ICallerContext. Use javax.ejb.EJBContext instead, to maintain the portability of the bean.
Typically ICallerContext is used together with the IServerContext interface.
Methods
The ICallerContext interface is described as follows:public interface ICallerContext
public java.security.Identity getCallerIdentity();
public boolean isCallerInRole(java.security.Identity role);
getCallerIdentity( ) returns the Identity object that identifies the caller.
The isCallerInRole( ) method returns true if the caller has the given role, where the role parameter describes the java.security.Identity of the role to be tested.
Neither of the specifications for servlets and EJBs describe a standard way of creating an instance of java.security.Identity. To create an instance within a iPlanet Application Server 6.0 application, use the following method from the IServerContext interface:
public java.security.Identity createIdentityByString(
String identity)
Examples
Example 1
The following sample code demonstrates the use of programmatic security from a servlet:
Example 2
The following sample code demonstrates the use of programmatic security from a servlet:
Example 3
The following sample code demonstrates the use of programmatic security from a bean.Both SessionContext and EntityContext inherit from javax.ejb.EJBContext. The container will invoke setSessionContext( ) or setEntityContext( ) on your bean and provide you with an instance before any business methods are executed.
// within a bean javax.ejb.SessionContext m_ctx; // method on javax.ejb.EJBContext Identity id = m_ctx.getCallerIdentity(); In addition, the isCallerInRole() method, available from ICallerContext and EJBContext, can be used to test for membership.
Related Topics
com.kivasoft.applogic.AppLogic class (deprecated),
com.kivasoft.dlm.GXContext class,
com.kivasoft.IContext Interface,
com.netscape.server.IServerContext Interfacejavax.ejb.EJBContext interface
IColumn Interface (deprecated)
IColumn is deprecated and is provided for backward compatibility only. New applications should use the interfaces java.sql.DatabaseMetaData or java.sql.ResultSetMetaData from the JDBC Core API.
The IColumn interface represents a column definition in a table. IColumn provides methods for obtaining descriptive information about a table column from the database catalog, which contains the column definition. Column attributes include the column name, precision, scale, size, table, and data type.
IColumn is part of the Data Access Engine (DAE) service.
To create an instance of this interface, use one of the following methods:
getColumn( ) or getColumnByOrd( ) in the IHierResultSet Interface (deprecated)
The following example shows creating an IColumn object:getColumn( ), getColumnByOrd( ), or enumColumns( ) in the ITable Interface (deprecated)
getColumn( ), getColumnByOrd( ), or enumColumns( ) in the IResultSet Interface (deprecated)
ITable tbl = conn.getTable("Products");
IColumn col = tbl.getColumnByOrd(1);
Example 1
The following example shows how to iterate through a table to get the names and types of the columns:
Example 2
The following example goes through all columns in a Products table and constructs an HTML string showing catalog information about each column:
Related Topics
getColumn( ) or getColumnByOrd( ) in the IHierResultSet Interface (deprecated)getColumn( ), getColumnByOrd( ), or enumColumns( ) in the ITable Interface (deprecated)
getColumn( ), getColumnByOrd( ), or enumColumns( ) in the IResultSet Interface (deprecated)
Returns the name of the column or alias.
Syntax
public String getName()
Usage
Use getName( ) when the name of the column is unknown and is required for subsequent operations.For computed columns in a query, specify aliases so that using getName( ) returns the alias name. Otherwise, the column can be identified only by ordinal position.
Do not rely on the case of the returned name. It might be all uppercase or mixed case, depending on the database.
Return Value
String representing the name of the column, or null for failure (such as insufficient memory).
Example
The following example shows how to iterate through a table to get the names of columns:
Determines whether null values are allowed in the column.
Syntax
public boolean getNullsAllowed()
Usage
A column may require data values. Use getNullsAllowed( ) if this information is unknown to determine, for subsequent operations, whether nulls are allowed or not.
Tip
For numeric columns that allow NULLs, the value is usually zero (0) in the column if a NULL is inserted. For more information, see your database vendor's documentation.
Return Value
True if the column allows nulls, or false if the column is defined as NOT NULL (requiring data values).
Example
The following example shows how to iterate through a table and return the column names, as well as whether null values are allowed in each column:
Returns the precision, which is the maximum length or maximum number of digits, of the column.
Syntax
public int getPrecision()
Usage
Use getPrecision( ) when the precision of the column is unknown and is required for subsequent operations.
Return Value
An int value representing the maximum length or maximum number of digits of the column, or zero for failure (such as the precision is unknown).
Example
The following example shows how to iterate through a table and return the column names, as well as the precision value of each column:
Returns the scale, which is the number of digits to the right of the decimal point, of a column of type double.
Usage
Use getScale( ) when the scale of the column is unknown and is required for subsequent operations.Use getScale( ) with numeric columns, including SQL DECIMAL, NUMERIC, and FLOAT data types.
The value returned from getScale( ) depends on the data type of the column. For example, it returns zero (0) for integers. For more information, see your database server documentation.
For computed columns in a result set, the value returned from getScale( ) depends on the data type of the evaluated expression.
Return Value
An int value representing the fixed number of digits to the right of the decimal point, or zero if unknown or not applicable.Returns the maximum length, in number of bytes, allowed for a value in this column.
Usage
Use getSize( ) when the maximum allowable length of the column is unknown and is required for subsequent operations. Note that getSize( ) does not return the actual size of data in the column.The value returned from getSize( ) depends on the data type of the column. For more information, see your database server documentation.
For computed columns in a result set, the value returned from getSize( ) depends on the data type of the evaluated expression.
Return Value
An int value representing the maximum length of the column, or zero for failure.
Example
The following example shows how to iterate through a table and return the column names, as well as the maximum allowable length of each column:
Returns the table object in which this column exists.
Syntax
public ITable getTable()
Usage
Use getTable( ) when the table definition of the column is unknown and is required for subsequent operations. For result set columns, this method returns a table object, which is a description of the columns in the result set.
Return Value
ITable object representing the table, or null for failure.
Related Topics
ITable Interface (deprecated)
Returns the data type of the column.
Use getType( ) when the data type of the column is unknown and is required for subsequent operations.
Return Value
An int value corresponding to one of the static variables, listed next, in the GX_DA_DATA_TYPES class.
In iPlanet Application Server applications, some public methods require an IContext object as a parameter. The IContext interface itself has no public methods. You do not create or destroy IContext objects, but you can obtain them in several ways.
Examples
The following examples describe different ways to obtain a context.
Example 1
From an AppLogic, an instance of this context is available as a member variable context within the superclass com.kivasoft.applogic.Applogic. The following code is used from within an AppLogic method:com.kivasoft.IContext kivaContext;
Example 2
From a servlet, the standard servlet context can be cast to IServerContext, and from there, a com.kivasoft.IContext instance can be obtained. The servlet code would look like this:ServletContext ctx = getServletContext();
com.netscape.server.IServerContext sc;
sc = (com.netscape.server.IServerContext) ctx;
com.kivasoft.IContext kivaContext = sc.getContext();
Example 3
As an alternative to Example 2, a caller can access the underlying AppLogic instance from a servlet and obtain the context there, as described in Example 1 for AppLogics. The servlet code would look like this:req2 = (HttpServletRequest2) req; // legal cast within iPlanet Application Server
AppLogic al = req2.getAppLogic();
com.kivasoft.IContext kivaContext;
Example 4
From a bean, the standard javax.ejb.SessionContext or javax.ejb.EntityContext can be cast to an IServerContext, and from there, a com.kivasoft.IContext instance can be obtained. In a bean, the code would look like this:javax.ejb.SessionContext m_ctx;
com.netscape.server.IServerContext sc;
// legal cast within iPlanet Application Server
sc = (com.netscape.server.IServerContext) m_ctx;
com.kivasoft.IContext kivaContext;
kivaContext = sc.getContext();
Example 5
From a Java extension, an instance of the context is supplied to the init( ) method of your extension, as shown by the following code:public int init(IObject obj) {
com.kivasoft.IContext kivaContext = (com.kivasoft.IContext) obj;
Related Topics
com.kivasoft.applogic.AppLogic class (deprecated),
com.kivasoft.dlm.GXContext class,
com.netscape.server.ICallerContext Interface,
com.netscape.server.IServerContext Interface
IDataConn Interface (deprecated)
IDataConn is deprecated and is provided for backward compatibility only. New applications should use the java.sql.Connection interface from the JDBC Core API.
The IDataConn interface represents a connection to a relational data source. IDataConn provides methods for preparing a query, executing a query, identifying table(s) to work with, and closing the connection explicitly. In addition, the data connection object is used in other operations for interacting with a data source.
IDataConn is part of the Data Access Engine (DAE) service. To create an instance of the IDataConn interface, use createDataConn( ) in the AppLogic class (deprecated), as shown in the following example:.
if((conn = createDataConn(0, GX_DA_DAD_DRIVERS.GX_DA_DRIVER_ODBC, "CATALOG", "CATALOG", "steve", "pass7878")) == null)
Related Topics
createDataConn( ) in the AppLogic class (deprecated)getDataConn( ) in the ITable Interface (deprecated)
addRow( ), deleteRow( ), and updateRow( ) in the ITable Interface (deprecated)
Explicitly closes the database connection.
Syntax
public int closeConn(
int dwFlags)dwFlags. Specify 0, or GX_DA_CLOSECONN_FLAGS.GX_DA_UNBIND_TRANS, which explicitly unbinds a physical connection from a transaction.
Usage
The Data Access Engine performs certain housekeeping tasks, such as shutdown and cleanup, automatically and intermittently. Use closeConn( ) to explicitly close a database connection and release system resources, such as when memory is low. Calling closeConn( ) breaks the virtual connection to the database and puts the physical connection back into the database connection cache.Closing the database connection changes the state of the IDataConn object to closed.
Close a database connection only after the AppLogic no longer needs it. A run-time error will occur if subsequent operations attempt to use a data connection object that has already been closed.
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
createDataConn( ) in the AppLogic class (deprecated)
Creates a new trigger object in the specified table.
Syntax
int createTrigger(
String pTable,
String pName,
String pCondition,
String pOptions,
String pSQLBlock);pTable. The table on which the trigger is defined. You can specify the name of the owner as a prefix to the table name, for example, "jim.myTable".
pName. The name of the trigger object to create.
pCondition. The condition that determines whether or not the SQL procedure (defined in the pSQLBlock parameter) executes. For example, you can specify that the SQL procedure executes only if a column contains a specific value:
"FOR EACH ROW WHEN(city = 'San Francisco')"
pOptions. The row operations that determine when the trigger executes. For example, you can specify that the trigger be activated BEFORE or AFTER an INSERT, UPDATE, and/or DELETE operation:
pSQLBlock. The definition of the SQL block to execute when the trigger goes into effect. Refer to your database documentation for information on the SQL block format.
Usage
A trigger is a SQL procedure associated with a table. It is automatically activated when a specified row operation, such as INSERT, UPDATE, and DELETE, is issued against the table. Use createTrigger( ) to specify the table and the data modification command that should activate the trigger, and the action or actions the trigger is to take.For specific information on supported trigger options and conditions, refer to the description of triggers in your database documentation.
After creating a trigger, enable it by calling enableTrigger( ). The following are exceptions to the rule:
Sybase does not support the enabling or disabling of triggers.
Oracle automatically enables a trigger when the trigger is created; you can optionally call enableTrigger( ), but it will have no effect.
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
disableTrigger( )
Disables a trigger associated with a specified table. This feature is supported by Oracle databases only.
Syntax
public int disableTrigger(
String pTable,
String pName);pTable. The table in which the trigger is located.
pName. The name of the trigger to disable.
Usage
Use disableTrigger( ) to temporarily stop a trigger from being activated. The trigger is disabled until it is enabled with enableTrigger( ). To remove a trigger from a table permanently, use dropTrigger( ).
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
createTrigger( )
Removes a trigger from a specified table.
Syntax
public int dropTrigger(
String pTable,
String pName);pTable. The table on which the trigger is defined.
pName. The name of the trigger to remove.
Usage
Use dropTrigger( ) to delete a trigger that is no longer required. To temporarily stop a trigger from being activated, use disableTrigger( ).
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
createTrigger( )
Enables a trigger for a specified table. This feature is supported by Oracle databases only.
Syntax
public int enableTrigger(
String pTable,
String pName);pTable. The table on which the trigger is defined.
pName. The name of the trigger to enable.
Usage
Use enableTrigger( ) to prepare a specified trigger for activation. Call enableTrigger( ) after you create a trigger with createTrigger( ), or to enable a trigger that was disabled with disableTrigger( ).
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
createTrigger( ); disableTrigger( )
Executes a flat query on the data connection.
Syntax
public IResultSet executeQuery(
int dwFlags,
IQuery pQuery,
ITrans pTrans,
IValList pProps)dwFlags. Specifies flags used to execute this query.
For synchronous operations, the default, specify zero or GX_DA_EXECUTEQUERY_FLAGS.GX_DA_EXEC_SYNC.
The AppLogic can pass both result set buffering and either synchronous or asynchronous queries as the flags parameter, as shown in the following example:For asynchronous operations, specify GX_DA_EXECUTEQUERY_FLAGS.GX_DA_EXEC_ASYNC.
To activate result set buffering, specify GX_DA_EXECUTEQUERY_FLAGS.GX_DA_RS_BUFFERING.
(GX_DA_EXECUTEQUERY_FLAGS.GX_DA_EXEC_ASYNC | GX_DA_EXECUTEQUERY_FLAGS.GX_DA_RS_BUFFERING)
pQuery. IQuery object that contains the flat query object to execute.
pTrans. ITrans object that contains the transaction to which this query applies, or null.
pProps. IValList object that contains query properties, or null for no properties. After instantiating an object of the IValList interface, set any of the following properties:
RS_BUFFERING turns on result set buffering when set to "TRUE".
If RS_BUFFERING is enabled and if the optional parameters are not specified, the global values in the registry are used instead.RS_INIT_ROWS specifies the initial size of the buffer, in number of rows. If the result set size exceeds this setting, a fetchNext( ) call will return the error GX_DA_FETCHNEXT_RESULTS.GX_DA_BUFFER_EXCEEDED.
RS_MAX_ROWS specifies the maximum number of rows for the buffer. If the result set size exceeds this setting, a fetchNext( ) call will return the error GX_DA_FETCHNEXT_RESULTS.GX_DA_BUFFER_EXCEEDED.
RS_MAX_SIZE specifies the maximum number of bytes for the buffer.
Before calling executeQuery( ), AppLogic must create a query by first calling createQuery( ) in the AppLogic class (deprecated) to create the IQuery object, then using methods in the IQuery Interface (deprecated) to define the query.
If the query is part of a transaction, before calling executeQuery( ), the AppLogic must first create the ITrans transaction object using createTrans( ) in the AppLogic class (deprecated), then begin the transaction using begin( ) in the ITrans Interface (deprecated), and then specify the ITrans object as a parameter when calling executeQuery( ).
Return Value
IResultSet object containing the result of the query, or null for failure (such as invalid tables or columns, or an invalid data comparison). If the result set is empty, calling getRowNumber( ) from the IResultSet Interface (deprecated) returns zero.
Related Topics
createDataConn( ) in the AppLogic class (deprecated)IResultSet Interface (deprecated)
Returns database and user information about the current database connection.
Syntax
public IValList getConnInfo()
Usage
When the client code calls the createDataConn( ) method in the AppLogic class to create a connection between the client and the specified database, it passes the following parameters: flags, driver, datasource, database, username, and password. Once a data connection has been established, you can call getConnInfo( ) to return the datasource, database, user, and password values.
Tip
To return the driver value, use getDriver( ).
Return Value
IValList object, or null for failure.
Returns registry information about the current database connection.
Syntax
public IValList getConnProps()
Usage
Use getConnProps( ) to get database connection information that the iPlanet Application Server administrator set through the Enterprise Administrator. The information is returned in an IValList object that contains the following keys and values:
The getConnProps( ) method might return other information depending on the database being used.
Applications typically use the database vendor information in conditional code that executes differently depending on the type of database.
Return Value
IValList object, or null for failure.
Related Topics
setConnProps( )
Returns the identifier of the data source driver that the current database connection is using.
Syntax
Usage
When the client code calls the createDataConn( ) method in the AppLogic class to create a connection between the client and the specified database, it passes the following parameters: flags, driver, datasource, database, username, and password. Once a data connection has been established, you can call various methods in the IDataConn interface to return the values that were passed to createDataConn( ).Call getDriver( ) to return the driver information.
Tip
To return the datasource, database, user, and password values, use getConnInfo( ).
Return Value
An int value corresponding to one of the static variables in the GX_DA_DAD_DRIVERS class.
Returns the table definition object for the specified table.
Syntax
public ITable getTable(
String szTable)szTable. Name of the table to request. This can include the schema name, for example, "jim.myTable." Do not use patterns or wildcards.
Usage
Use getTable( ) for the following reasons:
To change data in the table using methods in the ITable Interface (deprecated) to insert, update, and delete rows.
When the schema of a table is unknown, to obtain information about the table definition from the database catalog, such as table name, table columns, data connection, and so on.
Rule
The AppLogic usually calls getTable( ) only once to obtain a table definition. Subsequent calls return a separate ITable object that represents the same table. Each AppLogic can call getTable( ) and operate on its own copy of the table definition.If the table name is unknown, use getTables( ) to retrieve an IValList of tables in the data source, then use methods in the IValList interface and the Val class to iterate through the table names obtained and determine which table to retrieve.
To obtain additional information about individual columns, use the IColumn Interface (deprecated).
Return Value
ITable object, or null for failure (such as an invalid table name).
Related Topics
ITable Interface (deprecated)createDataConn( ) in the AppLogic class (deprecated)
Returns an IValList of database tables or views that are available to the specified user.
Syntax
public IValList getTables(
String szQualifier,
String szOwner,
String szTable)szQualifier. Specify null. Driver-dependent.
szOwner. Specify null, or a schema name, which returns tables for that schema.
szTable. Table or view name with wildcards, or null for all tables. Wildcards must be in the format supported by the data source. For example, you can use search patterns using the following characters:
Usage
Use getTables( ) when the list of available tables on the data source is unknown. The AppLogic can obtain a subset of available tables by specifying wildcards in the table name.The AppLogic must be logged in with sufficient privileges to obtain a list of tables from the database. For more information, see your database server documentation.
The AppLogic must specify a valid table name, view name, or name pattern. Aliases and synonyms are not supported for security reasons.
Tip
Use methods in the IValList interface and the Val class to iterate through the table names obtained and determine which table(s) to work with. Thereafter, use to access each table.
Return Value
IValList object containing a list of table names, or null for failure (such as if none are found to match the search expression).
Related Topics
ITable Interface (deprecated)createDataConn( ) in the AppLogic class (deprecated)
Creates an ICallableStmt object that contains a call to a stored procedure.
Syntax
public ICallableStmt prepareCall(
int dwFlags,
IQuery pQuery,
ITrans pTrans,
IValList pProps);
pQuery. The IQuery object that contains the call to a stored procedure. The stored procedure call should have been specified with the setSQL( ) method in the IQuery interface.
pTrans. ITrans object that contains the transaction associated with this callable statement, or null for no transaction. This same ITrans object must then be passed to the execute( ) method of the ICallableStmt interface.
Usage
Use prepareCall( ) to create a ICallableStmt object that contains a call to a stored procedure. After creating the callable statement, run it by calling execute( ) in the ICallableStmt interface.Before calling prepareCall( ), the AppLogic must create a query by first calling createQuery( ) in the AppLogic class (deprecated) to create the IQuery object, then using the setSQL( ) method in the IQuery Interface (deprecated) to define the call to a stored procedure.
When accessing a stored procedure on Sybase or MS SQL Server, input parameter names must be prefixed with the ampersand (&) character, for example, ¶m1. Other database drivers accept the ampersand, as well as, the colon (:) character. For all database drivers, input/output and output parameter names are prefixed with the colon (:) character, for example, :param2.
Example
Return Value
ICallableStmt object, or null for failure.
Related Topics
ICallableStmt Interface (deprecated)
Prepares a flat query object for subsequent execution.
Syntax
public IPreparedQuery prepareQuery(
int dwFlags,
IQuery pQuery,
ITrans pTrans,
IValList pProps)
pQuery. IQuery object that contains the query or statement to execute.
pTrans. ITrans object that contains the transaction to which this query applies, or null. This same object must then be passed to the execute( ) method of the IPreparedQuery interface.
Usage
Use prepareQuery( ) to prepare the query, then execute the prepared query using execute( ) in the IPreparedQuery Interface (deprecated). An application can also use prepareQuery( ) with result set buffering to pre-fetch result set data efficiently from a back-end database.
Rule
Before calling prepareQuery( ), AppLogic must create a query by first calling createQuery( ) in the AppLogic class (deprecated) to create the IQuery object, then using methods in the IQuery Interface (deprecated) to define the query.
Return Value
IPreparedQuery object, or null for failure.
Related Topics
IPreparedQuery Interface (deprecated)createDataConn( ) in the AppLogic class (deprecated)
Specifies registry values for the current database connection.
Syntax
public int setConnProps(
IValList pProps)pProps. A pointer to the IValList object that contains the connection properties to set in the registry. Use the following defined key names for the connection properties:
Key
Value
An integer indicating the number of slots set for free connections.
An integer indicating the initial number of slots in the connection cache.
Usage
Use setConnProps( ) to override database connection properties that the iPlanet Application Server administrator set through the Enterprise Administrator. To get the current connection properties programmatically, call getConnProps( ).
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
getConnProps( )
IDataConnSet Interface (deprecated)
IDataConnSet is deprecated and is provided for backward compatibility only. New applications should use the JDBC API to provide similar functionality.
The IDataConnSet interface represents a collection of data connections and associated query names. It is used in conjunction with loading a query file.
Use IDataConnSet when loading a hierarchical query from a file. The AppLogic first establishes a data connection with each database on which any queries will be run. Next, the AppLogic calls createDataConnSet( ) in the AppLogic class (deprecated) to create an empty IDataConnSet object, then populates this object with query name / data connection pairs.
In this way, the AppLogic can use parameterized queries and select and assign data connections dynamically at runtime. Finally, the AppLogic calls loadHierQuery( ) in the AppLogic class (deprecated) to create the hierarchical query object.
IDataConnSet is part of the Data Access Engine (DAE) service.
To create an instance of the IDataConnSet interface, use createDataConnSet( ) in the AppLogic class (deprecated), as shown in the following example:.
connSet = createDataConnSet();
Associates a query name with a data connection object and adds it to the IDataConnSet object.
Related Topics
createDataConnSet( ) in the AppLogic class (deprecated)
Associates a query name with a data connection object and adds it to the IDataConnSet object.
Syntax
public int addConn(
String pQueryName,
IDataConn pConn)pQueryName. Name of a query in the query file.
pConn. Name of the data connection object representing an active connection with the data source on which the query will be run.
Every named query in the qulery file must have a corresponding named query in the IDataConnSet object.
The AppLogic must first create the data connection object using createDataConn( ) in the AppLogic class (deprecated).
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
createDataConnSet( ) in the AppLogic class (deprecated)
The IEnumObject interface represents an enumeration object that contains IObject instances. Some methods that return a list of objects, such as enumEvents( ) in the IAppEventMgr interface, return an IEnumObject object.
The IEnumObject interface defines methods for counting and accessing the IObject instances in an IEnumObject.
Related Topics
enumEvents( ) in the IAppEventMgr Interface
Returns the number of IObject instances in an IEnumObject.
Usage
Use enumCount( ) to determine the number of objects to process before iterating through the IObject instances in the IEnumObject.
Return Value
The number of objects in an IEnumObject.
Example
In the following example, enumEvents( ) returns all the application events registered with the iPlanet Application Server in an IEnumObject. The enumCount( ) method is used in conjunction with enumNext( ) and enumReset( ) to access objects in the IEnumObject.
Related Topics
enumEvents( ) in the IAppEventMgr Interface
Returns the next IObject instance in an IEnumObject.
Syntax
public IObject enumNext()
Usage
Use enumNext( ) in conjunction with enumCount( ) and enumReset( ) to iterate through an IEnumObject.
Return Value
GXE.SUCCESS if the method succeeds.
Example
In the following example, enumEvents( ) returns all the application events registered with the iPlanet Application Server in an IEnumObject. The enumNext( ) method is used in conjunction with enumCount( ) and enumReset( ) to access objects in the IEnumObject.
Related Topics
enumEvents( ) in the IAppEventMgr Interface
Resets to the first IObject instance in an IEnumObject.
Syntax
public int enumReset(
int dwFlags)
Usage
Use enumReset( ) before iterating through an IEnumObject. Doing so ensures that iteration begins at the first IObject instance in the IEnumObject.
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
enumEvents( ) in the IAppEventMgr Interface
IError is deprecated and is provided for backward compatibility only. New applications should use JDBC exceptions instead. For example, the java.sql package provides exceptions such as BatchUpdateException, DataTruncation, SQLException, and SQLWarning.
The IError interface represents an error code object that consists of a code and a corresponding error message that originates from a facility, such as an operating system or a database. In this release, IError handles database errors only.
Use the methods in the IError interface to get error codes and messages returned by a database.
The IErrorinterface is implemented by the IDataConn object. To use it, cast IDataConn to the IError interface, as shown in the following example:
Method
Description
Returns a description of the facility that generated an error code.
Returns the current error code as a string.
Syntax
public String getErrorCode()
Usage
Use getErrorCode( ) after a database operation, such as running a stored procedure or executing a query, to retrieve the error code for debugging or error-handling purposes. The following is an example of a returned error code: "ORA-03130".
Tip
For ODBC, the error codes usually consist of the ODBC error code and the database error code separated by a space, for example, "S1000 1017". Sometimes just the ODBC error code, such as "S1000", is returned.
Return Value
The current error code as a string.
Related Topics
getErrorCodeNum( )
Returns the current error code as a number.
Syntax
public int getErrorCodeNum()
Usage
Use getErrorCodeNum( ) after a database operation, such as running a stored procedure or executing a query, to retrieve the error code for debugging or error-handling purposes.
Return Value
The current error code as a number. If the error code cannot be converted to a number, getErrorCodeNum( ) returns null. For example, an error code that contains letters, such as "S1000", cannot be converted to a number.
Related Topics
getErrorCode( )
Returns the message associated with the current error code.
Syntax
public String getErrorMessage(
String pCode)
Usage
Use getErrorMessage( ) after a database operation, such as running a stored procedure or executing a query, to retrieve the message associated with the current error code. The AppLogic can then display the message to users. The following is an example of a returned error message: "[ODBC][Visigenic driver][S1000]Connection attempt failed".
Return Value
The message associated with the current error code.
Related Topics
getErrorCode( )
Returns a description of the facility that generated an error code.
Syntax
public String getErrorFacility()
Usage
Use getErrorFacility( ) after a database operation, such as running a stored procedure or executing a query, to get information on which driver generated the current error code. The following is an example of a description returned by getErrorFacility( ): "ODBC DAD".
Return Value
The description of the facility that generated the current error code.
Related Topics
getErrorCode( )
IHierQuery Interface (deprecated)
IHierQuery is deprecated and is provided for backward compatibility only. New Java applications should use the standard servlet-JSP programming model.
For information about replacing IHierQuery functionality in existing applications, see the Migration Guide.
The IHierQuery interface represents a hierarchical query. IHierQuery provides methods for retrieving hierarchical information organized in nested levels of detail, as in the following example:
A hierarchical query combines multiple flat queries organized in cascading, parent-child relationships. Each query is an IQuery object containing data selection criteria. The IHierQuery object contains the definition of the hierarchical structure of parent-child relationships among IQuery objects.
To use a hierarchical query, the AppLogic first creates each individual query and defines its selection criteria. Next, it creates theIHierQueryobject and calls addQuery( ) repeatedly to add a child query to a parent query for each level of detail in the hierarchical query.
After the hierarchical query is constructed, the AppLogic calls its execute( ) method to run the hierarchical query on the target data source and retrieve a hierarchical result set in an IHierResultSet object.
Alternatively, the AppLogic can load a hierarchical query stored in a file. For more information, see loadHierQuery( ) and createDataConnSet( ) in the AppLogic class (deprecated).
To create an instance of the IHierQuery interface, use createHierQuery( ) in the AppLogic class (deprecated), as shown in the following example:
Method
Description
Adds a child query to a parent query, defining an additional level of detail in the hierarchical query.
Executes a hierarchical query and returns a hierarchical result set.
"> Example 2
Related Topics
createHierQuery( ) in the AppLogic class (deprecated)
Adds a child query to a parent query, defining an additional level of detail in the hierarchical query.
Syntax
public int addQuery(
IQuery pQuery,
IDataConn pConn,
String szAlias,
String szParent,
String szJoin)pQuery. IQuery object that contains the flat query object to append as a child to the parent query.
pConn. IDataConn object that contains the data connection where the child query will be executed. Each flat query in the hierarchical query can retrieve data from a different data source.
szAlias. Name used to uniquely identify this child query in the query hierarchy. AppLogic must specify a child name that is unique within the hierarchical query.
szParent. Name of the parent query to contain this child query. Use an empty string ("") for the highest level in the hierarchical query. When adding a child query to an existing parent query, the specified parent name must have already been specified in a previous addQuery( ) call.
szJoin. Join clause used to specify a join for this query, defining the relationship between a field in the child query and a field in the parent query. Use an empty string for the highest level in the hierarchical query. Use the following Netscape-compliant syntax for the join clause:
"ParentQuery.table.column='childQuery.table.column'"
Optionally, you can specify the schema:
"ParentQuery.schema.table.column='childQuery.schema.table.column'"
Note The only difference between the Netscape Application Server and SQL join syntax is that, with Netscape, you prepend the clause with the query name.
To refer to a field name in the parent query, include the parent query name before the field name, as shown in the following example, in which CITY is the name of the parent query:
hqr.addQuery(qryEMP, conn, "EMP", "CITY", "EMP.employee.city = 'CITY.city'");
Use the AND and OR operators to specify additional join conditions. Use parentheses to specify the order of precedence in complex join criteria.
Usage
Use addQuery( ) when constructing the hierarchical query to define the hierarchical relationships among child and parent queries. The number of nested levels, and thus the number of addQuery( ) calls, is limited only by system resources.The AppLogic must first create the data connection using createDataConn( ) in the AppLogic class (deprecated).
The AppLogic must then create the specified child query using createQuery( ) in the AppLogic class (deprecated). A separate child query must exist for every level of data.
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
createHierQuery( ) in the AppLogic class (deprecated)IDataConn Interface (deprecated)
Removes a child query from its parent query.
Syntax
public int delQuery(
String szName)szName. Name of the child query to remove.
Usage
Use delQuery( ) to remove a child query that is no longer needed. Any children of the deleted child query are also removed.
Rule
The specified child query must exist in the hierarchical query.
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
createHierQuery( ) in the AppLogic class (deprecated)loadHierQuery( ) in the AppLogic class (deprecated)
Executes a hierarchical query and returns a hierarchical result set.
Syntax
public IHierResultSet execute(
int dwFlags,
int dwTimeout,
IValList pProps)dwFlags. Specifies flags used to execute this hierarchical query.
For synchronous operations, the default, specify zero or GX_DA_EXECUTEQUERY_FLAGS.GX_DA_EXEC_SYNC.
The AppLogic can pass both result set buffering and either synchronous or asynchronous queries as the flags parameter, as shown in the following example:For asynchronous operations, specify GX_DA_EXECUTEQUERY_FLAGS.GX_DA_EXEC_ASYNC.
To activate result set buffering, specify GX_DA_EXECUTEQUERY_FLAGS.GX_DA_RS_BUFFERING.
(GX_DA_EXECUTEQUERY_FLAGS.GX_DA_EXEC_ASYNC | GX_DA_EXECUTEQUERY_FLAGS.GX_DA_RS_BUFFERING).
pProps. IValList object that contains query properties, or null for no properties. After instantiating an object of the IValList interface, set any of the following properties:
RS_BUFFERING turns on result set buffering when set to "TRUE".
If RS_BUFFERING is enabled and if the optional parameters are not specified, the global values in the registry are used instead..RS_INIT_ROWS specifies the initial size of the buffer, in number of rows. If the result set size exceeds this setting, a fetchNext( ) call will return the error GX_DA_FETCHNEXT_RESULTS.GX_DA_BUFFER_EXCEEDED.
RS_MAX_ROWS specifies the maximum number of rows for the buffer. If the result set size exceeds this setting, a fetchNext( ) call will return the error GX_DA_FETCHNEXT_RESULTS.GX_DA_BUFFER_EXCEEDED.
RS_MAX_SIZE specifies the maximum number of bytes for the buffer.
Usage
After constructing a hierarchical query using addQuery( ), the AppLogic uses execute( ) to execute the query on the database server. Results are returned in a hierarchical result set.
Rule
AppLogic must first construct the hierarchical query using addQuery( ).
Return Value
IHierResultSet object that contains the result set of the hierarchical query, or null for failure (such as invalid parameters).
Related Topics
createHierQuery( ) in the AppLogic class (deprecated)loadHierQuery( ) in the AppLogic class (deprecated)
IHierResultSet Interface (deprecated)
IHierResultSet Interface (deprecated)
IHierResultSet is deprecated and is provided for backward compatibility only. New Java applications should use the standard servlet-JSP programming model.
For information about replacing IHierResultSet functionality in existing applications, see the Migration Guide.
The IHierResultSet interface represents a hierarchical result set retrieved by a hierarchical query. IHierResultSet provides methods to iterate through rows in the hierarchical result set and retrieve information about each row. Alternatively, an AppLogic can process hierarchical result sets by passing them directly to the Template Engine using evalOutput( ) in the AppLogic class (deprecated).
IHierResultSet is part of the Data Processing Engine (DPE) service. To create an instance of IHierResultSet, use execute( ) in the IHierQuery Interface (deprecated), as shown in the following example:
hrs = hqry.execute(0, 0, null);
Example
The following code runs a hierarchical query and with the returned hierarchical result set, checks a user's access level to determine which listbox options to display:
Related Topics
createHierQuery( ) in the AppLogic class (deprecated)IHierQuery Interface (deprecated)
Returns the total number of rows retrieved so far from the data source for the specified child query.
Syntax
public int count(
String qryName)qryName. Name of the child query that generated the result set.
Usage
Use count( ) to return the current number of rows processed so far in the result set. If iterating through rows in a result set that has been completely returned, use count( ) to determine the current maximum number of rows to process.
Tip
If result set buffering is enabled, the AppLogic can use count( ) to find the current number of rows in the buffer.
Rule
The specified child query must exist in the result set.
Return Value
An int value representing the number of rows in the result set retrieved so far, or zero for failure (such as an invalid child query name).
Related Topics
createHierQuery( ) in the AppLogic class (deprecated)IHierQuery Interface (deprecated)
Returns the column definition for the column with the specified name in the specified child query.
Syntax
public IColumn getColumn(
String qryName,
String colName)qryName. Name of the child query that generated the result set.
colName. Name of the column. Must not be qualified with the schema name or table name (if necessary, use column alias to ensure that the colName is unambiguous).
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.The specified child query must exist in the result set.
Tips
Use getColumnByOrd( ) instead when the column position is known but its name is unknown.
Columns that are the result of query expressions or formulas, such as invoice.count * product.price, should have a column alias in the result set. AppLogic can call setFields( ) in the IQuery Interface (deprecated) to specify field aliases using the "as" keyword.
Return Value
IColumn object containing information from the retrieved column, or null for failure (such as an invalid child query name or column name).
// Obtain column information for UserID field IColumn col; col = hrs.getColumn("USERS", "UserID") . . . process column info using IColumn methods . . .
Related Topics
createHierQuery( ) in the AppLogic class (deprecated)IHierQuery Interface (deprecated)
IColumn Interface (deprecated)
Returns the column definition for the column in the specified ordinal position for the specified child query.
Syntax
public IColumn getColumnByOrd(
String qryName,
int colIndex)qryName. Name of the child query that generated the result set.
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 getColumnByOrd( ) when the data definition of the column is unknown and is required for subsequent operations. 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.The specified child query must exist in the result set.
Tip
Use getColumn( ) instead when the column name is known but its ordinal position is unknown.
Return Value
IColumn object containing information from the retrieved column, or null for failure (such as an invalid child query name or column name).
Example
// Obtain column information for UserID fieldIColumn col1, col2, col3, col4;
col1 = hrs.getColumnByOrd("USERS", 1)
col2 = hrs.getColumnByOrd("USERS", 2)
col3 = hrs.getColumnByOrd("USERS", 3)
col4 = hrs.getColumnByOrd("USERS", 4)
. . . process column info using IColumn methods . . .
Related Topics
createHierQuery( ) in the AppLogic class (deprecated)IHierQuery Interface (deprecated)
IColumn Interface (deprecated)
Returns the result set for a specified child query.
Syntax
public IResultSet getResultSet(
String qryName)qryName. Name of the child query that generated the result set to retrieve.
Usage
Use getResultSet( ) to retrieve and manipulate a particular child result set in the hierarchical result set. The AppLogic can then use methods in the IResultSet Interface (deprecated) to get data from the result set columns.
Rule
The specified child query must exist in the result set.
Return Value
IResultSet object , or null for failure (such as an invalid child query name).
Example
// Look up list of customers matching criteria from databaseIHierResultSet hrs = lookupCustomer(ssn, lastName, firstName, acctNum);
return handleOBSystemError("Could not retrieve database results");
// Check the result set to see if any customers are found
IResultSet rs = hrs.getResultSet("SelCusts");
Returns the number of the current row for the specified child query in the hierarchical result set.
Syntax
public int getRowNumber(
String qryName)qryName. Name of the child query that generated the result set.
Usage
When iterating through rows in a child set, use getRowNumber( ) to keep track of the number of rows processed.
Rule
The specified child query must exist in the result set.
Return Value
An int value representing the current row number in the child result set, or zero if the result set is empty or for failure (such as an invalid row or query name). 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 AppLogic calls getRowNumber( ), that means the result set is empty for the specified child query.
Example
// Create the hierarchical queryIHierQuery hqry = createHierQuery();
hqry.addQuery(qry, conn, "USERS", "", "");
IHierResultSet hrs = hqry.execute(0, 0, null);
TemplateMapBasic map = new TemplateMapBasic();
// Determine whether result returned match
if(hrs.getRowNumber("USERS")==0)
return result("No user matches loginname: "+wantedUser);
String access=rs.getValueString("USERS", "AccessLevel");
if(access.compareTo("AccessAdmin")==0)
selAdmin="<option selected>"+"AccessAdmin"+"</option>\n";
selNormal="<option>Normal</option>\n";
selAdmin="<option>"+"AccessAdmin"+"</option>\n";
selNormal="<option selected>Normal</option>\n";
String select="<select name=accessControlLevel>\n"+selNormal+selAdmin+"</select>";
TemplateMapBasic tMap=new TemplateMapBasic();
int ers = evalTemplate(template, (ITemplateData) rs, tMap);
return result("Failed to Generate HTML");
Related Topics
createHierQuery( ) in the AppLogic class (deprecated)IHierQuery Interface (deprecated)
Returns the value of a Date type column, as a string, from the specified child query in the result set.
Syntax
public String getValueDateString(
String qryName,
String colIName)qryName. Name of the child query that generated the result set.
colName. Name of the column from which to retrieve the date.
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:
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).
Related Topics
getValueDouble( )
Returns the value of a double type column from the specified child query in the result set.
Syntax
public double getValueDouble(
String qryName,
String colName)qryname. Name of the child query that generated the result set.
colName. Name of the column from which to retrieve the double value.
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).
Related Topics
getValueDateString( )
Returns the value of an int type column from the specified child query in the result set.
Syntax
public int getValueInt(
String qryName,
String colName)qryname. Name of the child query that generated the result set.
colName. Name of the column from which to retrieve the value.
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).
Related Topics
getValueDateString( )
Returns the value of a string type column from the specified child query in the result set.
Syntax
public String getValueString(
String qryName,
String colName)qryname. Name of the child query that generated the result set.
colName. Name of the column from which to retrieve the value.
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).
Related Topics
getValueDateString( )
Moves to the next row for the specified child query in the result set.
Syntax
public int moveNext(
String qryName)qryName. Name of the child query that generated the result set.
Usage
Use moveNext( ) when iterating through rows in the result set to retrieve the contents of the next sequential row.
Rule
The specified child query must exist in the result set.
Return Value
An int value for success (zero) or failure (non-zero, such as reaching the end of the result set). If the current row is the last row in the result set, calling moveNext( ) returns a non-zero int.
Related Topics
createHierQuery( ) in the AppLogic class (deprecated)IHierQuery Interface (deprecated)
Moves to the specified row for the specified child query in the result set.
Syntax
public moveTo(
String qryName,
int nRow)qryName. Name of the child query that generated the result set.
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.The specified child query must exist in the result set.
The specified row number must exist in the result set.
If RS_BUFFERING is turned on, AppLogic can move forward and backwards in the result set. However, if RS_BUFFERING is not turned on, AppLogic can move forward to subsequent rows only. AppLogic cannot return to rows that have been processed previously.
Tip
For certain database drivers, this operation may be very slow and should be avoided if possible.
Return Value
An int value for success (zero), or failure (non-zero, such as an invalid row number).
Related Topics
createHierQuery( ) in the AppLogic class (deprecated)IHierQuery Interface (deprecated)
IListRowSet is an extension to the javax.sql.RowSet interface that provides the methods necessary to populate a listbox in a JSP. Although anyone developing a iPlanet Application Server application can use IListRowSet, this interface is typically used in components generated by Netscape Application Builder.
IListRowSet replaces the IListDataSet interface from iAB 3.0.
Package
com.netscape.server.servlet.extension
Method
Description
Sets the item that appears as the default selection in a list.
Related Topics
com.netscape.server.servlet.extension.IRowSet2 interface,
javax.sql.RowSet interface
Syntax
public abstract void addListItem(String label, String value)label. The label for the list entry; this is not necessarily the name of the item as it appears in the list.
value. The value assigned to the label.
Usage
Use addListItem( ) with setListSelection( ) when working with an IListRowSet to create a selection list or a group of radio buttons.
Example
The following code fragment creates a data set as a list:IListRowSet ds = BaseUtils.createListRowSet(request,response,"myList");
ds.addListItem("Star Trek", "1");
ds.addListItem("Babylon 5", "2");
ds.addListItem("Red Dwarf", "3");
ds.addListItem("Crusade", "4");
ds.setListSelection("2"); // Babylon 5 is the default selection
To display this list on a web page, you might create a JSP containing the following code:
<OPTION VALUE="%gx type=cell id=myList.value% %/gx%"
id=myList.isEqualToExpression(
myList.value=myList.ListSelection)%SELECTED
%gx type=cell id=myList.label%%/gx%
Sets the item that appears as the default selection in a list.
Syntax
public abstract void setListSelection(String value)value. The value (not the label) in the list that appears as the default selection.
Usage
Use setListSelection( ) with addListItem( ) when working with data sets to create a selection list or a group of radio buttons.
The ILock interface provides concurrency control for objects operating in a multithreaded environment (for example, in applications that use distributed state).
AppLogics use locks to protect objects during concurrent operations. For example, state and session nodes implement this interface. Applications that access state or session data concurrently must synchronize using the methods in this interface.
A lock has the following attributes:
A lock mode. You can specify an exclusive or shared lock. An exclusive lock prevents other threads from accessing a locked object. You can also use the lock mode to specify that an operation may continue even if the desired locking mode is not available.
The ILock interface defines methods for locking and unlocking objects. It also defines a method for changing the lock mode.A caller ID. This setting provides a unique identifer for the caller that places or removes a lock. The identifier is an array of bytes.
Method
Description
Changes the lock mode of a currently locked object. This method is not available for the lock interface implemented by state and session objects.
Changes the lock on an object.
Note This method is not supported for locks on state and session nodes. State and session support only one lock mode, GXLOCK_EXCL, which cannot be changed.
Syntax
public int changeMode(
int dwOldMode,
int dwNewMode,
byte[] pID,
int nSize);dwOldMode. Current lock mode applied to an object. The mode is one of GXLOCK_EXCL (exclusive lock) or GXLOCK_SHARE (shared lock).
dwNewMode. New locking mode, one of GXLOCK_EXCL (exclusive lock) or GXLOCK_SHARE (shared lock). Optionally, the mode may also include GXLOCK_NOBLOCK if the operation should be allowed to continue if the desired locking mode is not available. If GXLOCK_NOBLOCK is not specified, then a thread is blocked if the desired locking mode is not available.
pID. ID of the caller requesting the change to the lock. This value is read only.
nSize. Size of the identifier.
Usage
Use changeMode( ) to change a lock on an object.
Return Value
An integer indicating success or failure of the lock mode change operation.
Syntax
public int lock(
int dwFlags,
byte[] pID,
int nSize);dwFlags. Locking mode, one of GXLOCK_EXCL (exclusive lock) or GXLOCK_SHARE (shared lock). Optionally, the mode may also include GXLOCK_NOBLOCK if the operation should be allowed to continue if the desired locking mode is not available. If GXLOCK_NOBLOCK is not specified, then a thread is blocked if the desired locking mode is not available.
GXLOCK_EXCL is the only mode currently supported for locking a state or session node. You cannot specify GXLOCK_NOBLOCK for state and session nodes.
pID. ID of the caller requesting the lock. This value is a byte array. For state and session objects that implement the locking interface, you can pass in a null value for pID because these implementations automatically use the ID of the calling thread for pID.
nSize. Size of the identifier.
Usage
Use lock( ) to lock an object.
Rules
When you lock certain kinds of nodes, the following rules apply:
After locking a parent state node, do not create or delete a child node under it.
After locking a state or session node, do not delete the node.
Return Value
An integer indicating success or failure of the lock operation.
Example
The following code shows how to lock and unlock a state node:IState2 marketnews = cacheroot.getStateChild("mktnews");
if (marketnews == null)
return;// we expect marketnews state node to be accessed concurrently
// let's lock itILock l = null;
int ret;
if (marketnews instanceof ILock)
{
l = (ILock)marketnews;
ret = l.lock(GXLOCK.GXLOCK_EXCL, null, 0);
if (ret != GXE.SUCCESS)
{
log("lock error");
return;
}
}
else
{
log("IState2 object doesn't implement the ILock interface");
return;
}
if (l == null)
return;// we now have the node locked in exclusive mode
// ..... do work ..........
// and unlock the noderet = l.unlock(GXLOCK.GXLOCK_EXCL, null, 0);
if (ret != GXE.SUCCESS)
log("unlock error");
Related Topics
AppLogic or ISession2 classes
Unlocks a previously locked object.
Syntax
public int unlock(
int dwFlags,
byte[] pID,
int nSize);dwFlags. The locking mode previously used to lock the object, either GXLOCK_EXCL (exclusive lock), or GXLOCK_SHARE (shared lock).
GXLOCK_EXCL is the only mode currently supported for unlocking a state or session node.
pID. The ID of the caller that requests lock removal. This value is a byte array. The ID must match the ID with which you set the lock.
Usually you pass in the ID of the executing thread that requests the lock. For state and session objects that implement the locking interface, you can pass in a null value for pID because these implementations automatically use the ID of the calling thread for pID.
nSize. Size of the identifier.
Usage
Use unlock( ) to remove a lock on an object.
Return Value
An integer indicating success or failure of the unlock operation.
Example
The following code shows how to lock and unlock a state node:IState2 marketnews = cacheroot.getStateChild("mktnews");
if (marketnews == null)
return;// we expect marketnews state node to be accessed concurrently
// let's lock itILock l = null;
int ret;
if (marketnews instanceof ILock)
{
l = (ILock)marketnews;
ret = l.lock(GXLOCK.GXLOCK_EXCL, null, 0);
if (ret != GXE.SUCCESS)
{
log("lock error");
return;
}
}
else
{
log("IState2 doesn't implement the ILock interface");
return;
}
if (l == null)
return;// we now have the node locked in exclusive mode
// ..... do work ..........
// and unlock the noderet = l.unlock(GXLOCK.GXLOCK_EXCL, null, 0);
if (ret != GXE.SUCCESS)
log("unlock error");
Related Topics
AppLogic or ISession2 classes
The IMailbox interface represents an electronic mailbox used for communicating with incoming and outgoing electronic mail. IMailbox provides methods for opening and closing a mailbox, as well as for receiving and sending mail messages. You must have access to either an SMTP or POP mail server.
To create an instance of the IMailbox interface, use createMailbox( ) in the AppLogic class (deprecated), as shown in the following example:
IMailbox mb = createMailbox("SMTPHostName", "myUserName",
"pass7878", "myEmailAddr@myOrg.com");
Related Topics
createMailbox( ) in the AppLogic class (deprecated)
Closes an open electronic mailbox session.
Usage
Use close( ) to close a mailbox session and commit changes on the mail server, if applicable. If sessions are open on both the POP and SMTP server, close( ) terminates both sessions.Closing a session does not terminate the IMailbox object. The AppLogic can later reopen a session using open( ).
Rule
The AppLogic can only close a mailbox session that is open.
Return Value
GXE.SUCCESS if the method succeeds.
Example
// Define the string parameters that will be passedString sendhost = "smtp.kivasoft.com";
String recvhost = "pop.kivasoft.com";
String pswd = "eugenesSecretPassword";
String useraddr = "eugene@kivasoft.com";
String sendTo[] = {"friend@otherhost.net", null};
String mesg = "Hi Friend, How are you?";
// Create an IMailbox instance
sendMB = createMailbox(sendhost, user, pswd, useraddr);
if (sendMB != null) // sendMB successfully created
// Open a session with the mail server
if (sendMB.open(GX_MBOX_OPEN_FLAG.OPEN_SEND)== GXE.SUCCESS)
Related Topics
open( )createMailbox( ) in the AppLogic class (deprecated)
Opens a session with the mail server.
Syntax
public int open(
int dwFlag)dwFlag. Access level used to open the mailbox. Specify one of the following options:
GX_MBOX_OPEN_FLAG.OPEN_RECV to receive emails. Sets up a session with the POP server only.
GX_MBOX_OPEN_FLAG.OPEN_SEND to send emails. Sets up a session with the SMTP server only.
GX_MBOX_OPEN_FLAG.OPEN_SEND |GX_MBOX_OPEN_FLAG.OPEN_RECV to send and receive emails.
Usage
Use open( ) to explicitly open a session with the mail server after instantiating the IMailbox object. Alternatively, the AppLogic can open a session after having closed a previous session using close( ).Depending on the setting of the dwFlag parameter, open( ) starts a session on the SMTP server only, on the POP server only, or on both servers at once (two separate sessions).
Rule
The AppLogic must call open( ) before calling other methods.
Tip
To conserve system resources, use only the access level you need. For example, if the AppLogic will only be sending electronic mail messages, specify GX_MBOX_OPEN_FLAG.OPEN_SEND, not GX_MBOX_OPEN_FLAG.OPEN_SEND |GX_MBOX_OPEN_FLAG.OPEN_RECV.
Return Value
GXE.SUCCESS if the method succeeds.
Example
// Define the string parameters that will be passedString sendhost = "smtp.kivasoft.com";
String recvhost = "pop.kivasoft.com";
String pswd = "eugenesSecretPassword";
String useraddr = "eugene@kivasoft.com";
String sendTo[] = {"friend@otherhost.net", null};
String mesg = "Hi Friend, How are you?";
// Create an IMailbox instance
sendMB = createMailbox(sendhost, user, pswd, useraddr);
if (sendMB != null) // sendMB successfully created
// Open a session with the mail server
if (sendMB.open(GX_MBOX_OPEN_FLAG.OPEN_SEND))
Related Topics
send( )createMailbox( ) in the AppLogic class (deprecated)
Retrieves electronic mail messages from the inbox.
Syntax
public IValList retrieve(
boolean bLatest,
boolean bDelete)bLatest. Specify true to retrieve the latest unread messages. Specify false to retrieve all messages in the inbox.
bDelete. Specify true to delete retrieved messages when the mailbox session is closed. Specify false to leave the retrieved messages on the mail server.
Usage
Use retrieve( ) to get unread messages from the inbox. Once retrieved, messages are marked as READ.
Rule
To use retrieve( ), the AppLogic must have first opened the mailbox session using open( ) and have specified either GX_MBOX_OPEN_FLAG.OPEN_RECV or GX_MBOX_OPEN_FLAG.OPEN_SEND |GX_MBOX_OPEN_FLAG.OPEN_RECV as the dwFlag parameter.
Tip
AppLogic can use retrieveReset( ) to undo changes (deletes, read flags) to messages in the inbox.
Return Value
IValList that contains the retrieved messages, or null for failure.
Example
// Create mailbox object to connect to a POP mail server// Only check messages received after the last open
// Remove retrieved messages from the mail server
// Create an IMailbox instance
recvMB = createMailbox(recvhost, user, pswd, useraddr);
if (recvMB.open(GX_MBOX_OPEN_FLAG.OPEN_RECV))
// Count the number of new messages
int numMsgs = recvMB.retrieveCount();
mesgList = recvMB.retrieve(Latest,Delete);
// Use IValList methods to iterate through
// the returned IValList. The keys in the
// IValList are the message numbers. The
// values are the email messages as strings
Related Topics
open( )createMailbox( ) in the AppLogic class (deprecated)
Counts the number of unread electronic mail messages in the inbox.
Syntax
public int retrieveCount()
Usage
Before calling retrieve( ), use retrieveCount( ) to count the number of retrievable messages in the inbox. The AppLogic might do this to avoid retrieving an empty inbox. If the AppLogic iterates through the messages after they have been retrieved, the AppLogic can call retrieveCount( ) to determine the maximum number of iterations required to process all available inbox messages.
Rule
To use retrieveCount( ), the AppLogic must have first opened the mailbox session using open( ) and have specified either GX_MBOX_OPEN_FLAG.OPEN_RECV or GX_MBOX_OPEN_FLAG.OPEN_SEND|GX_MBOX_OPEN_FLAG.OPEN_RECV as the dwFlag parameter.
Return Value
The number of available unread electronic mail messages in the inbox. The retrieveCount( ) method returns 0 for no messages and a negative number if an error ocurred.
Example
// Create mailbox object to connect to a POP mail server// Only check messages received after the last open
// Remove retrieved messages from the mail server
// Create an IMailbox instance
recvMB = createMailbox(recvhost, user, pswd, useraddr);
if (recvMB.open(GX_MBOX_OPEN_FLAG.OPEN_RECV))
// Count the number of new messages
int numMsgs = recvMB.retrieveCount();
mesgList = recvMB.retrieve(Latest,Delete);
// Use IValList methods to iterate through
// the returned IValList. The keys in the
// IValList are the message numbers. The
// values are the email messages as strings
Related Topics
open( )createMailbox( ) in the AppLogic class (deprecated)
Resets the status of retrieved messages in the mailbox from read to unread and abandons (rolls back) any message deletions.
Syntax
public int retrieveReset()
Usage
Use retrieveReset( ) to undo any changes made as a result of retrieving inbox messages with retrieve( ).To use retrieveReset( ), the AppLogic must have first opened the mailbox session using open( ) and have specified either GX_MBOX_OPEN_FLAG.OPEN_RECV or GX_MBOX_OPEN_FLAG.OPEN_SEND|GX_MBOX_OPEN_FLAG.OPEN_RECV as the dwFlag parameter.
Before calling retrieveReset( ), the AppLogic must first call retrieve( ).
To abandon changes made with retrieve( ), AppLogic must call retrieveReset( ) before calling close( ) or terminating the session.
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
open( )createMailbox( ) in the AppLogic class (deprecated)
Sends an electronic mail message to one or more mail addresses.
Syntax
public int send(
String[] ppTo,
String pMesg)ppTo. A list of email addresses, to which you want to send e-mail. The address or addresses must be supplied in a null-terminated array.
pMesg. Text of the electronic mail message. Use Internet mail formatting conventions for specifying advanced features in the message text, such as CC: or BCC: addresses, the Subject header, uuencode, MIME attachments, receipt notification, and so on. For syntax specifications, see your POP and SMTP protocol documentation.
To use send( ), the AppLogic must have first opened the mailbox session using open( ) and have specified either GX_MBOX_OPEN_FLAG.OPEN_SEND or GX_MBOX_OPEN_FLAG.OPEN_SEND|GX_MBOX_OPEN_FLAG.OPEN_RECV as the dwFlag parameter.
The specified addresses must be valid Internet mail addresses.
The specified message text must follow POP and SMTP protocol conventions.
Tip
The send( ) method automatically includes the FROM: address that the AppLogic specified in the pUserAddr parameter of createMailbox( ) in the AppLogic class (deprecated).
Return Value
GXE.SUCCESS if the method succeeds.
Example
// Define the string parameters that will be passedString sendhost = "smtp.kivasoft.com";
String recvhost = "pop.kivasoft.com";
String pswd = "eugenesSecretPassword";
String useraddr = "eugene@kivasoft.com";
String sendTo[] = {"friend@otherhost.net", null};
String mesg = "Hi Friend, How are you?";
// Create an IMailbox instance
sendMB = createMailbox(sendhost, user, pswd, useraddr);
if (sendMB != null) // sendMB successfully created
// Open a session with the mail server
if (sendMB.open(GX_MBOX_OPEN_FLAG.OPEN_SEND))
Related Topics
open( ),
retrieve( )createMailbox( ) in the AppLogic class (deprecated)
IObject Interface (deprecated)
The IObject interface is not necessary in the new application model. This interface is deprecated and is provided for backward compatiblity only.
The IObject interface is the base interface for all Netscape Application Server Java interfaces. Generally, iPlanet Application Server applications do not use this interface directly; they use the specialized derived interfaces instead.
IOrder is deprecated and is provided for backward compatibility only. New applications developed according to the servlet-JSP programming model do not need the functionality provided by IOrder.
The IOrder interface represents the current processing status of an asynchronous operation. IOrder provides methods for obtaining the status and return code of an asynchronous operation.
To run an asynchronous database operation, the AppLogic must specify GX_DA_EXECUTEQUERY_FLAGS.GX_DA_EXEC_ASYNC as the flags parameter in any of the following methods:
executeQuery( ) in the IDataConn Interface (deprecated)
To create an instance of the IOrder interface for an asynchronous query, use getOrder( ) in the IResultSet Interface (deprecated), as shown in the following example:.addRow( ), deleteRow( ), or updateRow( ) in the ITable Interface (deprecated)
Returns the processing status of the asynchronous operation on the database server: active, done, canceled, or unknown.
Related Topics
executeQuery( ) in the IDataConn Interface (deprecated)getOrder( ) in the IResultSet Interface (deprecated)
Returns the processing status of the asynchronous operation.
Syntax
public getStateIOrder getState()
Usage
Use getState( ) to return status information to use in error-handling code.
Return Value
A getStateIOrder object with three variables, each containing status and result code values. The three variables are described in the following table:
Example
Orders[] = new IOrder[1];Orders[0] = newRequestAsync(asyncGUIDStr, valIn, valOut);
log("Successfully invoked async AppLogic\n");
// wait for async applogic to finish (max 100 seconds)
nOrder = GX.WaitForOrder(Orders, context, 100);
return result("Error in executing async request:
order wait returned an error");
getStateIOrder state = Orders[0].getState();
if (state == null || state.pdwResult != GXE.SUCCESS)
return result("Error in executing async
log("Failed to invoke async AppLogic\n");
Related Topics
executeQuery( ) in the IDataConn Interface (deprecated)getOrder( ) in the IResultSet Interface (deprecated)
IPreparedQuery Interface (deprecated)
IPreparedQuery is deprecated and is provided for backward compatibility only. New applications should use the java.sql.PreparedStatement interface from the JDBC Core API.
The IPreparedQuery interface represents a prepared flat query. An IPreparedQuery object contains a SQL statement that has been compiled. This is what makes a statement "prepared." An AppLogic uses a prepared query when it needs to execute a SQL statement multiple time with different parameters.
For example, if an AppLogic runs an INSERT statement several times, each time with a different set of values to insert into the table, using a prepared query involves the following steps:
Prepare (compile) the INSERT statement with placeholder parameters whose values will be specified later.
By preparing the SQL statement, the database needs to compile the statement only once. Without prepared statements, the database must recompile each statement every time it is executed, which is less efficient.Specify a set of parameter values.
To create an instance of the IPreparedQuery interface, use prepareQuery( ) in the IDataConn Interface (deprecated), as shown in the following example:
pqry = conn.prepareQuery(0, qry, null, null);
Example
// Create the data connectionconn = createDataConn(0,GX_DA_DAD_DRIVERS.GX_DA_DRIVER_DEFAULT, "Orders", "Orders", "user", "password");
// Create the flat query and prepared query objects
// Set up the INSERT statement
qry.setSQL("INSERT INTO TABLE Products (ProductName, QuantityPerUnit) VALUES (:name, :quant)");
pqry = conn.prepareQuery(0, qry, null, null);
// Specify a set of query parameters, then execute
IValList params = GX.CreateValList()
params.setValString(":name","Chicken Dumplings");
params.setValString(":quant", "48 packages");
rs1 = pqry.execute(0, params, null, null);
// Specify different set of query parameters, then execute
params.setValString(":name", "Rice Noodles");
params.setValString(":quant", "96 packages");
rs2 = pqry.execute(0, params, null, null);
Related Topics
prepareQuery( ) in the IDataConn Interface (deprecated)
Syntax
public IResultSet execute(
int dwFlags,
IValList pParams,
ITrans pTrans,
IValList pProps)dwFlags. Specifies flags used to execute this prepared query. To activate result set buffering, specify GX_DA_EXECUTEQUERY_FLAGS.GX_DA_RS_BUFFERING. Otherwise, specify zero.
pParams. IValList object that contains parameters to pass to the prepared query. Parameters are used to execute the query.
pTrans. ITrans object that contains the transaction associated with this query, or null for no transaction.
pProps. IValList object that contains query properties, or null for no properties. After instantiating an object of the IValList interface, set any of the following properties:
RS_BUFFERING turns on result set buffering when set to "TRUE".
If RS_BUFFERING is enabled and if the optional parameters are not specified, the global values in the registry are used instead.RS_INIT_ROWS specifies the initial size of the buffer, in number of rows. If the result set size exceeds this setting, a fetchNext( ) call will return the error GX_DA_FETCHNEXT_RESULTS.GX_DA_BUFFER_EXCEEDED and result set buffering will be turned off.
RS_MAX_ROWS specifies the maximum number of rows for the buffer. If the result set size exceeds this setting, a fetchNext( ) call will return the error GX_DA_FETCHNEXT_RESULTS.GX_DA_BUFFER_EXCEEDED and result set buffering will be turned off.
RS_MAX_SIZE specifies the maximum number of bytes for the buffer.
Usage
Use execute( ) to run a prepared query. If the command contains parameters, instantiate an IValList object and use setValString( ) or setValInt( ) in the IValList interface to specify the parameter values to pass to the command.
Return Value
IResultSet object, or null for failure (such as an invalid parameter).
Example 1
// Create the data connectionconn = createDataConn(0,GX_DA_DAD_DRIVERS.GX_DA_DRIVER_DEFAULT, "Orders", "Orders", "user", "password");
// Create the flat query and prepared query objects
// Set up the INSERT statement
qry.setSQL("INSERT INTO TABLE Products (ProductName, QuantityPerUnit) VALUES (:name, :quant)");
pqry = conn.prepareQuery(0, qry, null, null);
// Specify a set of query parameters, then execute
IValList params = GX.CreateValList();
params.setValString(":name","Chicken Dumplings");
params.setValString(":quant", "48 packages");
rs = pqry.execute(0, params, null, null);
. . . process result set . . .
// Specify different set of query parameters, then execute
params.setValString(":name", "Rice Noodles");
params.setValString(":quant", "96 packages");
rs = pqry.execute(0, params, null, null);
. . . process result set . . .
Example 2
// Set up result set buffering for prepared query// . . . data connection and flat query already set up . . .
// Turn on result set buffering
props.setValString("RS_BUFFERING", "TRUE");
// Specify the maximum number of rows to buffer
props.setValInt("RS_MAX_ROWS", 50);
pqry = conn.prepareQuery(0, qry, null, props);
params.setValString(":name","Chicken Dumplings");
params.setValString(":quant", "48 packages");
rs = pqry.execute(GX_DA_EXECUTEQUERY_FLAGS.GX_DA_RS_BUFFERING, params, null, null);
. . . process result set . . .
Related Topics
IValList Interface (deprecated)prepareQuery( ) in the IDataConn Interface (deprecated)
Specifies the parameters for a prepared query.
Syntax
public int setParams(
int dwFlags
IValList pParams)
pParams. Pointer to an IValList object that contains parameters to pass to the prepared query.
Usage
To pass parameters to the prepared query using setParams( ), you must pass NULL for the pParams parameter in execute( ).
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
IValList Interface (deprecated)prepareQuery( ) in the IDataConn Interface (deprecated)
IQuery is deprecated and is provided for backward compatibility only. New applications should use the java.sql.Statement interface from the JDBC Core API. Note that IQuery is independent of a database connection, whereas JDBC's Statement interface is derived from a connection.
The IQuery interface represents a flat query. IQuery provides methods for specifying and obtaining the criteria used to select data from a data source. The AppLogic uses IQuery member methods to specify all parts of the SQL SELECT statement, including the SELECT, FROM, GROUP BY, HAVING, ORDER BY, and WHERE clauses.
To run a flat query, the AppLogic performs the following steps:
Creates an IQuery object using createQuery( ) in the AppLogic class (deprecated).
The AppLogic can also use IQuery methods to obtain information about query criteria when the criteria are unknown. Before executing the query on the data source, the AppLogic can evaluate and, if necessary, dynamically change the query criteria.Specifies query criteria using methods in the IQueryinterface.
Executes the query, passing the loaded IQuery object to executeQuery( ) in the IDataConn Interface (deprecated).
Processes the result set using methods in the IResultSet Interface (deprecated).
To create an instance of the IQuery interface, use the createQuery( ) method in the AppLogic class, as shown in the following example:.
Example 1
// Create the flat query objectqry.setFields("CustomerID, Customer");
qry.setWhere("Customer"+"="+String.valueOf(custId));
IResultSet rs=conn.executeQuery(0, qry, null, null);
// Check for a non empty result
if((rs!=null)&&(rs.getRowNumber()>0))
return result("Sorry, this user ("+
firstName+" "+lastName+") already exists");
. . . process the result set . . .
Example 2
// Create a database connectionif((conn = openBugDB())==null) return 0;
// Pull all the parms we need from the valIn
if((wantedUser = valIn.getValString("WantedUser"))==null)
return result("Missing information from form.");
// Create the flat query object
qry.setFields("Name, Password, UserType, AccessLevel, Email, ExtID");
query.setWhere("UserID"+"="+wantedUser.hashCode());
Related Topics
createQuery( ) in the AppLogic class (deprecated)executeQuery( ) in the IDataConn Interface (deprecated)
IResultSet Interface (deprecated)
Returns a comma-separated list of arbitrary SQL expressions or columns to be included in the result set of the query.
Syntax
public IBuffer getFields()
Usage
In a SQL SELECT statement, the first clause specifies the SELECT keyword as well as the list of columns to be retrieved in the result set.Use getFields( ) when the requested columns in a query are unknown, such as when using a query from another source. The AppLogic can analyze this list to determine the names of the columns as well as the order in which they will appear in the result set. Before executing or re-executing the query, the AppLogic can evaluate and, if necessary, dynamically change columns and column order in the query by calling setFields( ).
To use a query obtained from another source such as a file, the AppLogic can call getFields( ) and other getXXXX( ) member methods to test the query statement before submitting it to the server for processing. The AppLogic can then use the setXXXX( ) member methods to change the statement and avoid lengthy queries or syntax errors.
Use Util.toString( ) to convert the contents of the returned memory buffer into a String.
Return Value
An IBuffer object that contains a comma-separated list of columns that the query defines for the result set, starting with the first column and proceeding sequentially, left to right.
Example
// Get the columns specified in the query's SELECT clauseqryFields = Util.toString(qry.getFields());
Related Topics
createQuery( ) in the AppLogic class (deprecated)
Returns the GROUP BY clause of the query.
Syntax
public IBuffer getGroupBy()
Usage
In a SQL SELECT statement, the GROUP BY clause specifies rows to summarize into aggregate rows using column functions (such as SUM or MAX) or column names.Use getGroupBy( ) when the GROUP BY clause of the query is unknown, such as when using a query from another source. Before executing the query, the AppLogic can evaluate and, if necessary, dynamically change the GROUP BY clause by calling setGroupBy( ).
To use a query obtained from another source such as a file, the AppLogic can call getGroupBy( ) and other getXXXX( ) member methods to test the query statement before submitting it to the server for processing. The AppLogic can then use the setXXXX( ) member methods to change the statement and avoid lengthy queries or syntax errors.
Use Util.toString( ) to convert the contents of the returned memory buffer into a String.
Return Value
An IBuffer object that contains the GROUP BY clause of the query, or null for failure.
Example
// Obtain the GROUP BY clause specified in the queryqryGroup = Util.toString(qry.getGroupBy());
Related Topics
createQuery( ) in the AppLogic class (deprecated)
Returns the HAVING clause of the query.
Syntax
public IBuffer getHaving()
Usage
In a SQL SELECT statement, the HAVING clause specifies which of the aggregate rows returned by the GROUP BY clause are selected for the result set.Use getHaving( ) when the HAVING clause of the query is unknown, such as when using a query from another source. Before executing the query, the AppLogic can evaluate and, if necessary, dynamically change the HAVING clause by calling setHaving( ).
To use a query obtained from another source such as a file, the AppLogic can call getHaving( ) and other getXXXX( ) member methods to test the query statement before submitting it to the server for processing. The AppLogic can then use the setXXXX( ) member methods to change the statement and avoid lengthy queries or syntax errors.
Use Util.toString( ) to convert the contents of the returned memory buffer into a String.
Return Value
An IBuffer object that contains the HAVING clause of the query, or null for failure.
Example
// Obtain the HAVING clause specified in the queryqryHaving = Util.toString(qry.getHaving());
Related Topics
createQuery( ) in the AppLogic class (deprecated)
Returns the ORDER BY clause of the query.
Syntax
public IBuffer getOrderBy()
Usage
In a SQL SELECT statement, the ORDER BY clause specifies one or more columns by which rows in the result set are sorted, as well as whether they appear in ascending or descending ASCII order.Use getOrderBy( ) when the ORDER BY clause of the query is unknown, such as when using a query from another source. Before executing the query, the AppLogic can evaluate and, if necessary, dynamically change the ORDER BY clause by calling setOrderBy( ).
Rule
Some database vendors have restrictions on the ordering and usage of ORDER BY clauses. Read your database vendor's documentation carefully and test queries to ensure that they return the desired results.To use a query obtained from another source such as a file, the AppLogic can call getOrderBy( ) and other getXXXX( ) member methods to test the query statement before submitting it to the server for processing. The AppLogic can then use the setXXXX( ) member methods to change the statement and avoid lengthy queries or syntax errors.
Use Util.toString( ) to convert the contents of the returned memory buffer into a String.
Return Value
An IBuffer object that contains the ORDER BY clause of the query, or null for failure.
Example
// Obtain the ORDER BY clause specified in the queryqryOrder = Util.toString(qry.getOrderBy());
Related Topics
createQuery( ) in the AppLogic class (deprecated)
Returns the SQL pass-through statement associated with the query.
Syntax
public IBuffer getSQL()
Usage
Use getSQL( ) when the query string is unknown, such as when using a query from another source. Before executing the query, the AppLogic can dynamically change the SQL statement by calling setSQL( ).
Rule
If a query is set using setSQL( ) as well as the setXXXX( ) methods, the setSQL( ) string will be executed, not the string specified by setXXXX( ).To use a query obtained from another source such as a file, the AppLogic can call getSQL( ) and other getXXXX( ) member methods to test the query statement before submitting it to the server for processing. The AppLogic can then use the setXXXX( ) member methods to change the statement and avoid lengthy queries or syntax errors.
Use Util.toString( ) to convert the contents of the returned memory buffer into a String.
Return Value
An IBuffer object that contains the SQL pass-through statement of the query (as a single concatenated string), or null for failure.
Example
// Obtain the SELECT statement specified in the queryqrySelect = Util.toString(qry.getSQL());
Related Topics
createQuery( ) in the AppLogic class (deprecated)
Returns a comma-separated list of tables in the FROM clause of the query.
Syntax
public IBuffer getTables()
Usage
In a SQL SELECT statement, the FROM clause specifies one or more source tables, views, or table aliases to search in the query. In iPlanet Application Builder, the AppLogic can obtain table names only.Use getTables( ) when the FROM clause of the query is unknown, such as when using a query from another source. Before executing the query, the AppLogic can evaluate and, if necessary, dynamically change the FROM clause by calling setTables( ).
To use a query obtained from another source such as a file, the AppLogic can call getTables( ) and other getXXXX( ) member methods to test the query statement before submitting it to the server for processing. The AppLogic can then use the setXXXX( ) member methods to change the statement and avoid lengthy queries or syntax errors.
Use Util.toString( ) to convert the contents of the returned memory buffer into a String.
Return Value
An IBuffer object that contains the FROM clause of the query, or null for failure.
Example
// Obtain the FROM clause specified in the queryqryFrom = Util.toString(qry.getTables());
Related Topics
createQuery( ) in the AppLogic class (deprecated)
Returns the WHERE clause of the query.
Syntax
public IBuffer getWhere()
Usage
In a SQL SELECT statement, the WHERE clause specifies the search condition and determines which rows in the table are selected for the result set.Use getWhere( ) when the WHERE clause of the query is unknown, such as when using a query from another source. Before executing the query, the AppLogic can evaluate and, if necessary, dynamically change the WHERE clause by calling setWhere( ).
To use a query obtained from another source such as a file, the AppLogic can call getWhere( ) and other getXXXX( ) member methods to test the query statement before submitting it to the server for processing. The AppLogic can then use the setXXXX( ) member methods to change the statement and avoid lengthy queries or syntax errors.
Use Util.toString( ) to convert the contents of the returned memory buffer into a String.
Return Value
An IBuffer object that contains the WHERE clause of the query, or null for failure.
Example
// Obtains the WHERE clause specified in the queryqryWhere = Util.toString(qry.getWhere());
Related Topics
createQuery( ) in the AppLogic class (deprecated)
Specifies the list of columns and computed fields to be included in the result set of the query. Required method when writing a query.
Syntax
public int setFields(
String szFields)szFields. List of field names, separated by commas, or an asterisk (*) to include all fields. Extra whitespace characters are ignored. Use the AS keyword to specify field aliases. Defaults to all fields (*).
Usage
In a SQL SELECT statement, the first clause specifies the SELECT keyword as well as the list of columns and computed fields to be retrieved in the result set. The AppLogic can specify field aliases using the AS keyword in the setFields( ) parameter list.A computed field is the result of an expression using either of the following kinds of expressions:
Mathematical functions, including SQL string, numeric, time, date, system, and data type conversion functions and mathematical operators
Aggregate functions, including SUM, COUNT, MIN, MAX, AVG, to summarize values per column across a group of rows. These functions are commonly used in conjunction with the GROUP BY clause, which the AppLogic can specify using setGroupBy( ).
Rules
Use ANSI 92 SQL-compliant syntax for the field list.
Use implementation-specific SQL syntax extensions only on data sources that support them. Using extensions may compromise portability across platforms.
Any specified column names must appear in one of the tables specified in setTables( ). Table qualified names are permitted, such as "prod.name,emp.name".
Tip
For computed fields, use the AS keyword so that the AppLogic can process the column in the result set by alias name.
Return Value
GXE.SUCCESS if the method succeeds.
Example 1
// Create the flat query object// Specify list of fields to retrieve in the result set
qry.setFields("Name, Password, UserType, AccessLevel, Email, ExtID as ID");
query.setWhere("UserID"+"="+wantedUser.hashCode());
Example 2
// Specify result set fields, specifying alias for calculationqry.setFields("ProdID, ProdPrice * ProdQty AS ExtPrice");
Example 3
// Parentheses specify mathematical operator precedenceqry1.setFields("(product.price * invoice.quantity) / 100 as total, invoice.id");
qry2.setFields("invoice.id, product.price * 0.06 as tax");
Example 4
// COUNT and SUM aggregate functions and alias name for resultqry1.setFields("COUNT(invoice.id) as totalSold");
qry2.setFields("SUM(city.population) as urbanPopulation");
Related Topics
createQuery( ) in the AppLogic class (deprecated)
Specifies the GROUP BY clause of the query, determining how rows are grouped and calculated.
Syntax
public int setGroupBy(
String szGroupBy)szGroupBy. GROUP BY clause of the query, using standard SQL syntax.
Usage
In a SQL SELECT statement, the GROUP BY clause specifies rows to combine using column functions (such as SUM or MAX) or column names. Such groupings are called aggregate rows, which are single rows in a result set that combine data from a group of database rows with one or more column values in common.Use ANSI 92 SQL-compliant syntax for the GROUP BY clause.
Use implementation-specific SQL syntax extensions only on data sources that support them. Using extensions may compromise portability across platforms.
Return Value
GXE.SUCCESS if the method succeeds.
Example
IQuery query=createQuery();qry.setTables("CTLinvoice,CTLcust,CTLinvprod,CTLcatalog");
qry.setFields("FirstName, LastName, BillAddr1, BillAddr2,
sum(Quantity) as ProductsBought,
sum(quantity*price) as AmountSpent,
quantity/count(*) as ProdsPerVisit,
sum(quantity*price/count(*) as spentPerVisit")
qry.setWhere("Customer=CustomerId and Invoice=InvoiceId and
datePlaced >= start and datePlaced"<=end");
// Group customers by first name
qry.setOrderBy("Visits desc");
Related Topics
createQuery( ) in the AppLogic class (deprecated)
Specifies the HAVING clause of the query, determining which aggregate rows qualify for inclusion in the result set.
Syntax
public int setHaving(
String szGroupBy)szGroupBy. HAVING clause of the query, using standard SQL syntax.
Usage
The HAVING clause is used in conjunction with the aggregate functions (SUM, AVG, and so on) and the GROUP BY clause. In a SQL SELECT statement, the HAVING clause specifies a condition that determines which aggregate rows are selected for the result set. The HAVING clause restricts the number of aggregate rows retrieved in the result set. If unspecified, all aggregate rows will be retrieved.Use ANSI 92 SQL-compliant syntax for the HAVING clause.
Use implementation-specific SQL syntax extensions only on data sources that support them. Using extensions may compromise portability across platforms.
Tips
The order in which you specify a HAVING clause, in relation to other query clauses, may affect which records are retrieved in the result set. See your RDBMS server documentation for more information.
To improve the AppLogic performance, be sure to specify a HAVING or WHERE clause to avoid retrieving rows unnecessarily, especially for large tables.
Return Value
GXE.SUCCESS if the method succeeds.
Example
// Set condition on aggregate rows to anqry.setHaving("AverageAmt > 1000");
Related Topics
createQuery( ) in the AppLogic class (deprecated)
Specifies the ORDER BY clause of the query, determining how rows are sorted in the result set.
Syntax
public int setOrderBy(
String szOrderBy)szOrderBy. ORDER BY clause of the query, using standard SQL syntax. Supports the ASC and DESC keywords for sorting.
Usage
In a SQL SELECT statement, the ORDER BY clause specifies one or more columns by which rows in the result set are sorted. The AppLogic can also specify whether records appear in ascending (the default) or descending ASCII order using the ASC and DESC keywords, respectively.Use ANSI 92 SQL-compliant syntax for the ORDER BY clause.
Use implementation-specific SQL syntax extensions only on data sources that support them. Using extensions may compromise portability across platforms.
Any specified column names must appear in one of the columns specified in setFields( ).
Some database vendors have restrictions on the ordering and usage of ORDER BY clauses. Read your database vendor's documentation carefully and test queries to ensure that they return the desired results.
Return Value
GXE.SUCCESS if the method succeeds.
Example
IQuery qry=createQuery();qry.setTables("CTLinvoice,CTLcust,CTLinvprod,CTLcatalog");
qry.setFields("FirstName, LastName, BillAddr1, BillAddr2,
sum(Quantity) as ProductsBought,
sum(quantity*price) as AmountSpent,
quantity/count(*) as ProdsPerVisit,
sum(quantity*price/count(*) as spentPerVisit")
qry.setWhere("Customer=CustomerId and Invoice=InvoiceId and
datePlaced >= start and datePlaced <= end");
// Sorts rows in result set by number of visits
qry.setOrderBy("Visits desc");
Related Topics
createQuery( ) in the AppLogic class (deprecated)
Specifies the SQL statement to be passed directly to the data source.
Syntax
public int setSQL(
String szSQL)szSQL. SQL statement, using standard SQL syntax, to execute on the target data source. Specify a single, concatenated string. Do not use semicolon (;) characters or other vendor-specific statement delimiters.
Usage
The AppLogic can use setSQL( ) as an alternative to using other iPlanet Application Builder methods, such as constructing queries, inserting, updating, and deleting rows, and managing transactions. The AppLogic can also use setSQL( ) to run specialized SQL statements, such Data Definition Language (DDL) commands, Data Control Language (DCL) commands, and so on.Use ANSI 92 SQL-compliant syntax for the SQL statement.
Use implementation-specific SQL syntax extensions only on data sources that support them. Using extensions may compromise portability across platforms.
The AppLogic must be logged in with sufficient privileges to permit any operations requested in the passed-through SQL statement.
If inserting or updating rows in a table, the AppLogic must specify values that are valid. For example, the AppLogic cannot omit specifying a value for any column defined as NOT NULL and without a DEFAULT value, such as keys.
Using setSQL( ) overrides all previous calls to setXXXX( ) member methods for this query object. If a query is set using setSQL( ) as well as the setXXXX( ) methods, the setSQL( ) string will be executed, not the string specified by setXXXX( ).
If the statement is part of a transaction, the AppLogic must first create an instance of the ITrans Interface (deprecated) using createTrans( ) in the AppLogic class (deprecated). The AppLogic must then call begin( ) before executing the statement and, after executing the statement, call commit( ) or rollback( ) as appropriate.
Tip
To determine whether a column is defined as NOT NULL, use getNullsAllowed( ) in the IColumn Interface (deprecated).
Return Value
GXE.SUCCESS if the method succeeds.
Example 1
// Pass SELECT statement to setSQL()qry.setSQL("SELECT empName, empSalary FROM employees WHERE empSalary > 10000");
IResultSet rs=conn.executeQuery(0, query, null, null);
System.out.println("Writing to database");
Example 2
// Pass INSERT command to setSQL()qry.setSQL("INSERT into employees (empSalary) values (29)");
// Pass UPDATE command to setSQL()
qry.setSQL("UPDATE employees SET empSalary = 12000 WHERE empSalary = 10000");
Example 3
// Pass DELETE command to setSQL()qry.setSQL("DELETE FROM employees WHERE empSalary < 10000");
Related Topics
createQuery( ) in the AppLogic class (deprecated)Vendor documentation regarding SQL programming for the specific data source that is the target of the SQL statement.
Specifies the FROM clause of the query, identifying one or more tables to be queried. Required method when writing a query.
Syntax
public int setTables(
String szTables)szTables. List of table names separated by commas. Whitespace characters are ignored.
Usage
In a SQL SELECT statement, the FROM clause specifies one or more source tables, views, or table aliases to search in the query. In iPlanet Application Builder, the AppLogic can specify table names only.Use ANSI 92 SQL-compliant syntax for the FROM clause.
Use implementation-specific SQL syntax extensions only on data sources that support them. Using extensions may compromise portability across platforms.
The AppLogic can specify table names but not table aliases or view names.
The AppLogic can use the same table several times in a query. To do so, specify a different alias name each time the table is used.
Example 1
// Specify invoice, customer, invoice, and catalog tablesqry.setTables("CTLinvoice,CTLcust,CTLinvprod,CTLcatalog");
qry.setFields("FirstName, LastName, BillAddr1, BillAddr2,
sum(Quantity) as ProductsBought,
sum(quantity*price) as AmountSpent,
quantity/count(*) as ProdsPerVisit,
sum(quantity*price/count(*) as spentPerVisit")
qry.setWhere("Customer=CustomerId and Invoice=InvoiceId and
datePlaced >= start and datePlaced <= end");
Example 2
// Specify same table, using as keyword, for different usersqry.setTables("customer, customer as cust2")
Related Topics
createQuery( ) in the AppLogic class (deprecated)
Specifies the WHERE clause of the query, determining which rows qualify for inclusion in the result set.
Syntax
public int setWhere(
String szWhere)szWhere. WHERE clause of the query, using standard SQL syntax.
Usage
In a SQL SELECT statement, the WHERE clause specifies the search condition and determines which rows in the table are selected for the result set. The WHERE clause restricts the number of rows retrieved in the result set. If unspecified, all rows in the source table will be retrieved.Use ANSI 92 SQL-compliant syntax for the WHERE clause.
Use implementation-specific SQL syntax extensions only on data sources that support them. Using extensions may compromise portability across platforms.
Tip
To improve AppLogic performance, be sure to specify a HAVING or WHERE clause to avoid retrieving rows unnecessarily, especially for large tables.
Return Value
GXE.SUCCESS if the method succeeds.
Example 1
// Obtain user info from the user databaseqry.setFields("FirstName, LastName, BillAddr1, BillAddr2,
BillCity, BillState, BillZip");
qry.setWhere("CustomerId"+"="+cusId+" and
"+ "Password"+"='"+password+"'");
IResultSet rs=conn.executeQuery(0, qry, null, null);
if((rs==null)||(rs.getRowNumber()==0))
. . . process result set . . .
Example 2
// Specify WHERE clause for two different queriesqry1.setWhere("urbanPopulation >= 1000000");
qry2.setWhere("region = 'West' or region = 'East'");
Related Topics
createQuery( ) in the AppLogic class (deprecated)
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:
rs = conn.executeQuery(0, qry, null, null);
Example
The following code copies the data from all the rows in a result set into a log file: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)
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.
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:IResultSet rs = conn.executeQuery(0, query, null, null);
htmlString += "<h2>Products Table</h2>";
while ((col = rs.enumColumns()) != null) {
htmlString += "Column Name = ";
htmlString += ", Column Type = ";
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.
The columns might not be returned in the order in which they are defined in the database catalog.
Test for null to determine when the last column has been retrieved.
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:IResultSet rs = conn.executeQuery(0, query, null, null);
htmlString += "<h2>Products Table</h2>";
while ((col = rs.enumColumns()) != null) {
htmlString += "Column Name = ";
htmlString += ", Column Type = ";
Related Topics
IColumn Interface (deprecated)
Retrieves the next row in the result set.
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).
If the AppLogic needs to iterate through the result set more than once, be sure to start with the first row again by calling moveTo( ) and specifying row number 1. This works only when buffering is enabled.
If result set buffering is enabled, the AppLogic can use moveTo( ) to go to any row in the buffer.
Return Value
GXE.SUCCESS if the method succeeds. The AppLogic can test for the following return values:
GX_DA_FETCHNEXT_RESULTS.GX_DA_END_OF_FETCH indicates that the end of the result set has been reached.
GX_DA_FETCHNEXT_RESULTS.GX_DA_BUFFER_EXCEEDED indicates that the buffer size has been exceeded. When the buffer is exceeded, subsequent rows are still fetched and still buffered, but GX_DA_FETCHNEXT_RESULTS.GX_DA_BUFFER_EXCEEDED is returned for each overflow row.
Example
The following code copies the data from all the rows in a result set into a log file: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)
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.Use getColumnByOrd( ) instead when the column position is known but its name is unknown.
Columns that are the result of query expressions or formulas, such as invoice.count * product.price, should have a field alias for the column in the result set. Otherwise, the AppLogic can refer to the column only by its ordinal position. The AppLogic calls setFields( ) in the IQuery Interface (deprecated) to specify field aliases.
Return Value
IColumn object, or null for failure (such as an invalid column name).
Example
// Determine whether the column name is validif((col=rs.getColumn("CustID"))==null)
// otherwise, process column using IColumn methods ...
Related Topics
IColumn Interface (deprecated)executeQuery( ) in the IDataConn Interface (deprecated)
execute( ) in the IPreparedQuery Interface (deprecated)
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 validif((col=rs.getColumnByOrd(colOrd))==null)
// otherwise, process column using IColumn methods . . .
Related Topics
IColumn Interface (deprecated)executeQuery( ) in the IDataConn Interface (deprecated)
execute( ) in the IPreparedQuery Interface (deprecated)
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.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* cEmail*cPhone)==0)
return result("Can't map columns");
Related Topics
executeQuery( ) in the IDataConn Interface (deprecated)execute( ) in the IPreparedQuery Interface (deprecated)
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)
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).The AppLogic can determine the status of the query (active, done, cancelled, or unknown) using getState( ) in the IOrder Interface (deprecated).
Alternatively, use WaitForOrder( )in theGX class (deprecated), which waits until the asynchronous operation is done, to determine the processing status of an asynchronous query.
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)
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.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)
Returns the processing status of the asynchronous database operation on the database server.
Usage
Use getStatus( ) to return status information to use in error-handling code.
Return Value
One of the following:
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).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.The data type of the column must be longvarbinary or equivalent database vendor binary type.
You cannot call getValueBinaryPiece( ) for a row after you call fetchNext( ).
Tips
To determine the total size of the binary data that has been retrieved, use getValueSize( ).
To retrieve binary data of which the total size is less than 64Kb, use getValueBinary( ).
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:rs = conn.executeQuery(0, query, null, null);
if (rs != null && rs.getRowNumber() > 0)
BlobChunk = rs.getValueBinaryPiece(1, expectSize);
System.out.println("got a full chunk," +
System.out.println("got a partial chunk," +
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:
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);if((rs==null)||(rs.getRowNumber()==0)||(colName==null))
int colOrd=rs.getColumnOrdinal(colName);
if((col=rs.getColumnByOrd(colOrd))==null)
case GX_DA_DATA_TYPES.GX_DA_TYPE_STRING:
valStr = rs.getValueString(colOrd);
case GX_DA_DATA_TYPES.GX_DA_TYPE_LONG:
valStr=String.valueOf(rs.getValueInt(colOrd));
case IGX_DA_DATA_TYPES.GX_DA_TYPE_DATE:
valStr=rs.getValueDateString(colOrd);
case GX_DA_DATA_TYPES.GX_DA_TYPE_DOUBLE:
valStr=String.valueOf(rs.getValueDouble(colOrd));
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: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);
// Retrieve values from the result set
rs.getValueString(rs.getColumnOrdinal("ProdName"));
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: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);
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:IResultSet rs=conn.executeQuery(0, query, null, null);
if((rs==null)||(rs.getRowNumber()>0))
// Pull the current inventory and name for the product
rs.getValueInt(rs.getColumnOrdinal("COL_INVENTORY"));
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: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);
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( )
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: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);
// Retrieve values from the result set
rs.getValueString(rs.getColumnOrdinal("ProdName"));
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: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);
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.To determine the actual size of the TEXT data, use getValueSize( ).
If the value of the data is of type LONGTEXT, use getValueTextPiece( ).
Return Value
A String object, or null for failure (such as an invalid column number or data type mismatch).
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.The data type of the column must be LONGTEXT or database equivalent.
Call getValueTextPiece( ) until you get all the data before calling fetchNext( ) again.
Tips
To determine the actual size of the LONGTEXT data, use getValueSize( ). The actual size of the data determines the number of times you need to call getValueTextPiece( ).
For data of type TEXT, use getValueText( ).
Return Value
A String object, or null for failure (such as an invalid column number or data type mismatch).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.The specified row number must exist in the result set.
If row buffering is not enabled for the result set, the AppLogic can move forward to subsequent rows only. The AppLogic cannot return to rows that have been processed previously.
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)
Returns the total number of rows retrieved thus far from the data source.
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).htmlString += rs.getValueString(DESCRIPTION_COL);
// Truncate the report after 10 rows.
} while (rs.fetchNext() == GXE_SUCCESS);
Related Topics
executeQuery( ) in the IDataConn Interface (deprecated)execute( ) in the IPreparedQuery Interface (deprecated)
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.
IRowSet2 is an extension to the javax.sql.RowSet interface. IRowSet2 includes a set of methods that are needed for some of the server's backend. In particular, this interface includes initialization methods and some "set" methods that associate a RowSet to a particular servlet request or servlet response.
Although anyone developing a iPlanet Application Server application can use IRowSet2, this interface is intended for use in components generated by Netscape Application Builder.
IRowSet2 replaces the IDataSet interface from iAB 3.0.
Package
com.netscape.server.servlet.extension
Method
Description
Retrieves the name under which the RowSet is stored in the HttpServletRequest object.
Related Topics
javax.sql.RowSet interface
Retrieves the name under which the RowSet is stored in the HttpServletRequest object.
Syntax
public abstract String getName()
Usage
Use getName( ) to retrieve the name of a RowSet. If the RowSet is built over the ITemplateData interface, then the retrieved name is also the group name.
Related Topics
setName( ),
setAttribute( ) in class javax.servlet.http.HttpServletRequest,
ITemplateData interface
Initializes the RowSet for execution.
Syntax
public abstract void init()
Usage
Use init( ) to initialize the RowSet. For example, you can call init( ) to load a query from a file.
Related Topics
initMetaInfo( ),
DBRowSet class
Initializes the RowSet to match specific metadata.
Syntax
public boolean initMetaInfo(
OrderedHash metaData) throws SQLExceptionmetaData. An OrderedHash of NTV properties. The RowSet will be initialized with these properties.
Usage
Use initMetaInfo( ) to initialize a RowSet. This method is called by BaseUtils.initRowSets( ) when the RowSet is created.The metaData parameter specifies the properties stored in a method in the NTV list. The properties specify the query file name, the query name, the connection name, and the input bindings for the query parameters. In this way, the RowSet is initialized so as to match the properties stored in the NTV-list method.
The initMetaInfo( ) method must be called when the RowSet is constructed; that is, before init( ). For example, you can call initMetaInfo( ) to set the filename and query for a subsequent query-load.
Return Value
Returns false if initialization fails.
Syntax
public abstract void setName(
String newName)newName. The name you want to call this RowSet.
Usage
Use setName( ) to set the name of the RowSet. This method must be called when the RowSet is constructed. You can also use getName( ) to retrieve the name of the RowSet.Note that the setName( ) method does not store the RowSet into the request under the name specified in this call.
Sets the request for this RowSet.
Syntax
public abstract void setRequest(
HttpServletRequest request)request. The HttpServletRequest object.
Usage
Use setRequest( ) and setResponse( ) to set the request and response objects for this RowSet. These methods must be called when the RowSet is constructed. Calling these methods will associate the RowSet with a particular servlet request or servlet response.
Sets the response for this RowSet.
Syntax
public abstract void setResponse(
HttpServletResponse response)response. The HttpServletResponse object.
Usage
Use setRequest( ) and setResponse( ) to set the request and response objects for this RowSet. These methods must be called when the RowSet is constructed. Calling these methods will associate the RowSet with a particular servlet request or servlet response.
ISequence Interface (deprecated)
ISequence is deprecated and is provided for backward compatibility only.
The ISequence interface represents a sequence in an underlying database. Sequences are implemented in the database server to provide unique, incremental numbers assigned to records in a database. For example, the AppLogic can create a customer ID sequence to generate customer IDs, or create a purchase order sequence to generate purchase order numbers.
The ISequence interface provides methods to determine the current sequence value or to increment to the next sequence value. Sequences are useful for many types of applications, such as order entry applications.
The ISequence interface is part of the Data Access Engine (DAE) service.
To create an instance of the ISequence interface , use createSequence( ) in the ISequenceMgr Interface (deprecated), as shown in the following example:
Related Topics
createSequence( ) in the ISequenceMgr Interface (deprecated)
Deletes the sequence from the database.
Usage
Use drop( )to remove a sequence from the database. Be careful when using this method. If the database implements the sequence as a field in a table, drop( ) will delete the entire table, not just the sequence field. If the database implements the sequence as an object, as does Oracle for example, drop( ) deletes only the sequence object.Typically, once you start a sequence there is no reason to delete it. The sequence is normally used to create a permanent, unique numbering system for data in a database. However, you might use drop( ) if you are using the sequence mechanism to generate unique sequential numbers for a temporary programmatic purpose.
Return Value
GXE.SUCCESS if the method succeeds
Related Topics
createSequence( ) in the ISequenceMgr Interface (deprecated)
Returns the current value in the sequence.
Syntax
public int getCurrent();
Usage
Use getCurrent( ) to obtain the current value of the sequence without actually incrementing the sequence value.Alternatively, use getNext( ) to increment the sequence and obtain its incremented value.
Rule
For Oracle databases, the session must first call getNext( ) before it can call getCurrent( ).
Tip
UnlikegetNext( ) , calling getCurrent( ) does not change the value of the sequence.
Return Value
An int value representing the current value of the sequence, or -1 for failure.
Related Topics
createSequence( ) in the ISequenceMgr Interface (deprecated)
Increments the sequence and returns its incremented value.
Usage
Use getNext( ) to increment and return the value of the sequence by the amount specified in the increment parameter in the createSequence( ) method in the ISequenceMgr Interface (deprecated). The incrementation value is always a positive integer.Alternatively, use getCurrent( ) to obtain the current value of the sequence without incrementing the sequence.
Return Value
An int value representing the next (incremente)d value of the sequence, or -1 for failure.For Informix and Sybase databases, the session that creates the sequence must call getNext( ) at least once before any other session can call getSequence( ) in the ISequenceMgr Interface (deprecated).
For Oracle databases, the session must first call getNext( ) before it can call getCurrent( ).
Tip
Successive calls to getNext( ) return successive integers.conn = createDataConn(0, GX_DA_DAD_DRIVERS.GX_DA_DRIVER_ODBC,
"salesDB", "salesDB", "steve", "pass7878");
// Cast the connection to an ISequenceMgr interface
seq = ((ISequenceMgr) conn).createSequence("mySeq", "orders.ID", 100, 1, null)
// To start the sequence, call getNext().
// Use the sequence number to perform the task for
qry.setSQL("INSERT into orders (ID) values ("+ seqVal +")," +
"(cust) values ("+ custname +")");
Related Topics
createSequence( ) in the ISequenceMgr Interface (deprecated)
ISequenceMgr Interface (deprecated)
ISequenceMgr is deprecated and is provided for backward compatibility only.
The ISequenceMgr interface provides methods for creating and retrieving an ISequence object, which represents a sequence in an underlying database. Sequences provide unique, incremental numbers assigned to records in a database. After creating a sequence by calling createSequence( ), the AppLogic can use methods in the ISequence Interface (deprecated) to retrieve sequence values.
The ISequenceMgr interface is part of the Data Access Engine (DAE) service.
The ISequenceMgr interface is implemented by the IDataConn object. To use it, cast IDataConn to the ISequenceMgr interface, as shown in the following example:
Method
Description
Returns an existing sequence object for the specified sequence name in the underlying database.
Related Topics
ISequence Interface (deprecated)
Creates a new sequence object in the underlying database.
Syntax
public ISequence createSequence(
String szName,
String szCol,
int dwStart,
int dwIncrement,
String szOptions);szName. Name of the sequence. The name can be simple (such as "mySeq") or qualified with the name of the database owner (such as "mary.mySeq").
szCol. Name of the column in the database table to use if the database supports sequence column types. For more information, see your database vendor's documentation. If null, defaults to "SEQVAL".
dwStart. Starting value of the sequence. Must be a positive integer.
dwIncrement. Value by which to increment the sequence with each call to getNext( ). Must be a positive integer. Defaults to one (1). Not all databases support this feature. For more information, see your database vendor's documentation.
szOptions. Additional sequence creation options that are database vendor-specific:
For Oracle, these are options to the "CREATE Sequence"command.
For more information, see your database vendor's documentation.For SQL Server (Sybase and Microsoft) databases, these are column options for the "CREATE Table"command.
Usage
Use createSequence( ) to create a new ISequence object, representing an incremental number generator, with the specified starting value. The AppLogic can then use methods in the ISequence Interface (deprecated) to obtain the current or next value of this sequence object.Sequences provide unique, incremental numbers assigned to records in a database. For example, you can create a customer ID sequence to generate customer IDs, or create a purchase order sequence to generate purchase order numbers.
Tip
For Oracle databases, createSequence( ) creates a sequence object. For Sybase, Informix, and Microsoft SQL Server databases, createSequence( ) creates a table object with a sequence column.
Return Value
ISequence object, or null for failure (such as an invalid database connection).conn = createDataConn(0, GX_DA_DAD_DRIVERS.GX_DA_DRIVER_ODBC,
"salesDB", "salesDB", "steve", "pass7878");
// Cast the connection to an ISequenceMgr interface
seq = ((ISequenceMgr) conn).createSequence("mySeq", "orders.ID", 100, 1, null)
// To start the sequence, call getNext().
// Use the sequence number to perform the task for
qry.setSQL("INSERT into orders (ID) values ("+ seqVal +")," +
"(cust) values ("+ custname +")");
Related Topics
ISequence Interface (deprecated)
Returns an existing sequence object, for the specified sequence name, from the underlying database.
szName. Name of the sequence. The name can be simple (such as "mySeq") or qualified with the name of the database owner (such as "mary.mySeq").
szCol. Name of the column in the database table to use if the database supports sequence column types. For more information, see your database vendor's documentation. If null, defaults to "SEQVAL".
Usage
Use getSequence( ) to obtain the ISequence object with the specified name in the underlying database. The AppLogic can then use methods in the ISequence Interface (deprecated) to obtain the current or next value of this sequence object.Sequences provide unique, incremental numbers assigned to records in a database. For example, you can create a customer ID sequence to generate customer IDs, or create a purchase order sequence to generate purchase order numbers.
Use createSequence( ) to create the ISequence object.
The specified sequence name must be valid.
For Informix and Sybase databases, the session that creates the sequence must call getNext( ) at least once before any other session can call getSequence( ).
Return Value
ISequence object, or null for failure (such as an invalid sequence name).
Related Topics
ISequence Interface (deprecated)iAS
The IServerContext interface provides a way to access iAS-specific server interfaces from within servlets or EJBs. From servlets, the standard servlet context can be cast to an IServerContext object. From EJBs, a javax.ejb.EJBContext object can be cast to an IServerContext.
IServerContext is often used together with the ICallerContext interface.
Related Topics
com.kivasoft.applogic.AppLogic class (deprecated),
com.kivasoft.dlm.GXContext class,
com.kivasoft.IContext Interface,
com.netscape.server.ICallerContext Interface,javax.ejb.EJBContext interface
Creates an instance of java.security.Identity.
Syntax
public java.security.Identity createIdentityByString(
String identity)identity. The name to associate with the Identity object.
Usage
Neither of the specifications for servlets and EJBs describe a standard way of creating an instance of java.security.Identity. The createIdentityByString( ) method overcomes this limitation. Use this method to create an Identity instance within a iPlanet Application Server 6.0 application.Once you create the Identity, you can then (for example) pass it to a subsequent test for equality or use it as the role parameter of the isCallerInRole( ) method. The isCallerInRole( ) method is available in both javax.ejb.EJBContext and com.netscape.server.ICallerContext.
Return Value
A java.security.Identity object with the given name.
Retrieves the com.netscape.server.ICallerContext object.
Syntax
public ICallerContext getCallerContext()
Usage
Use this method within servlets to identify the caller context.Currently, the Servlet API specification provides no way to obtain the caller's principal from within a servlet. By contrast, the EJB specification defines the javax.ejb.EJBContext.getCallerPrincipal( ) method.
The getCallerContext( ) method is provided to add support for programmatic security from servlets. However, after this support is added to the Servlet API specification, the getCallerContext( ) method will be deprecated.
Return Value
The ICallerContext object that identifies the caller context within the servlet.
Retrieves the com.kivasoft.IContext object.
Syntax
public com.kivasoft.IContext getContext()
Usage
Use this method within servlets or EJBs. The getContext( ) method lets you access iAS-specific application modules or extensions that run in a pre-iAS-6.0 environment.The retrieved IContext object is the old iPlanet Application Server 2.x style context. The getContext( ) method is especially useful when combined with the functions from the com.kivasoft.dlm.GXContext class.
Example
Assume you have declared the following bean member variable containing SessionContext:public transient javax.ejb.SessionContext m_ctx = null;
The following sample code shows a bean implementation method that needs to invoke some iPlanet Application Server 2.x functionality:
// obtain 2.x style KIVA context from standard bean context
com.netscape.server.IServerContext sc;
// cast the standard servlet context or bean context
sc = (com.netscape.server.IServerContext) m_ctx;
com.kivasoft.IContext gxContext = sc.getContext();
// Use the context with GXContext class to access 2.x functionality.
// In this case, choose a logging operation
com.kivasoft.dlm.GXContext.Log(
com.kivasoft.types.GXLOG.GXEVENTTYPE_INFORMATION,
"Send this informational message to server log");
Return Value
The IContext object that identifies the context within the servlet or EJB.
IServletErrorHandler Interface
The interface com.netscape.server.servlet.extension.HttpServletRequest2 uses IServletErrorHandler to inform the user of validation errors or other types of errors.
Although anyone developing an application for iPlanet Application Server can use IServletErrorHandler, this interface is typically used in components generated by Netscape Application Builder.
Package
com.netscape.server.servlet.extension
Performs error handling for input parameter validation.
Syntax
public abstract int handleInputValueError(
HttpServletRequest request,
String name,
int errorType)request. The HttpServletRequest containing the invalid input.
name. The parameter name that failed validation.
errorType. An integer value identifying the error type. The error type is passed in by the HttpServletRequest2.validate( ) method. Values for possible error types are listed under the validate( ) method.
Usage
Typically, the handleInputValueError( ) method is never called directly by the application programmer. Instead, this method is called by HttpServletRequest2.validate( ) for each error that is found during input parameter validation.handleInputValueError( ) is called if a parameter fails its metadata-driven validation. You can use this method in one of several ways:
Use the default handling. As an option, you can call getServletErrorHandler( ) on the request and delegate to the retrieved error handler instead.
The default behavior of handleInputValueError( ) is to add values into three validation vectors. These vectors are listed in three methods of HttpServletRequest2: getErrorCodes( ), getErrorMsgs( ), and getErrorVars( ).Use the default handling, but change the template to be streamed. This case is presented in Examples.
Handle the error completely by yourself. This case is presented in Examples.
To override the default behavior, implement IServletErrorHandler and implement handleInputValueError( ) to handle errors related to input parameter validation. Before calling validate( ), call setServletErrorHandler( ) on the HttpServletRequest2 object.
Tip
It is recommended that you standardize error handling, so you may want to place error handling functionality in the default BaseServlet.
Return Value
This method returns any of the following integer values:
Example
The following code fragment uses the default handling but changes the template that is streamed. Typically, you would create this code in an inner class of the servlet that uses the error handler.public class foo implements IServletErrorHandler
// Store the old servlet error handler somewhere
public foo (HttpServletRequest2 request)
m_old = request.getServletErrorHandler();
// Handle the error as before, but set additional information
public int handleInputValueError(
m_old.handleInputValueError(request, name, errorType);
request.setAttribute("AddlInfo", "name failed");
// Not interested in session variables,
// so just delegate to the old handler
public int handleSessionVariableError(
return m_old.handleSessionVariableError(request, name, errorType);
// Handle the validation error appropriately
if (errorType == ERROR_VALIDATION_FAILED)
BaseUtils.includeJSP(request, response, "MyErrorTemplate.jsp");
return FAIL_DONT_STREAM_ERROR;
// handle the other errors by delegation
return m_old.streamError(request,response,errorSrc,errorType)
In your servlet, you call the validate( ) method after setting the error handler that validate( ) will use when it reports errors:
IServletErrorHandler handler = new foo((HttpServletRequest2)request);
((HttpServletRequest2)request).setServletErrorHandler(handler);
Related Topics
handleSessionVariableError( ),
HttpServletRequest2 interface
Performs error handling for session validation.
Syntax
public abstract int handleSessionVariableError(
HttpServletRequest request,
String name,
int errorType)request. The HttpServletRequest containing the invalid session.
name. The parameter name that failed validation.
Usage
Typically, the handleSessionVariableError( ) method is never called directly by the application programmer. Instead, this method is called by HttpServletRequest2.validate( ) for each error that is found during session validation.handleSessionVariableError( ) is called if a session variable fails its metadata-driven validation. You can use this method in one of several ways:
Use the default handling. As an option, you can call getServletErrorHandler( ) on the request and delegate to the retrieved error handler instead.
The default behavior of handleSessionVariableError( ) is to add values into three validation vectors. These vectors are listed in three methods of HttpServletRequest2: getErrorCodes( ), getErrorMsgs( ), and getErrorVars( ).Use the default handling, but change the template to be streamed.
To override the default behavior, implement IServletErrorHandler and implement handleSessionVariableError( ) to handle errors related to session validation. Before calling validate( ), call setServletErrorHandler( ) on the HttpServletRequest2 object.
Tip
It is recommended that you standardize error handling, so you may want to place error handling functionality in the default BaseServlet.
Return Value
This method returns any of the following integer values:
Examples
See handleInputValueError( ) for examples.
Related Topics
handleInputValueError( ),
HttpServletRequest2 interface
Sends a standard error as a data stream.
Syntax
public abstract int streamError(
HttpServletRequest request,
HttpServletResponse response,
Object errorSource,
int errorType) throws IOException, ServletExceptionrequest. The HttpServletRequest object.
response. The HttpServletResponse object.
errorSource. The object containing information about the source of the error.
errorType. An integer value identifying the error type to report. Specify one of the following values:
Usage
Typically, the streamError( ) method is called directly by the application programmer as well as by HttpServletRequest2.validate( ) for validation errors. In particular, only the variants of validate( ) that stream an error will call the streamError( ) method. This applies to the two variants of validate( ) that take an HttpServletResponse object.In addition, streamError( ) may be called by BaseUtils.initRowSets( ) when an exception occurs, or streamError( ) may be called by programmer-defined code.
To override the default behavior, implement IServletErrorHandler and implement streamError( ) to define the template or exception to stream when a validation error (or other type of error) occurs. Before calling validate( ), call setServletErrorHandler( ) on the HttpServletRequest2 object.
Return Value
This method returns any of the following integer values. By default, FAIL_DONT_STREAM_ERROR is returned.
Related Topics
HttpServletRequest2 interface
ISession2 Interface (deprecated)
The ISession2 interface is deprecated and is provided for backward compatibility only. New applications should use the methods provided by the standard javax.servlet.http.HttpSession interface. In addition, iPlanet Application Server provides the HttpSession2 interface, an extension to HttpSession that supports applications that must call AppLogics.
For more information, see the Programmer's Guide (Java) or the Migration Guide.
The ISession2 interface represents a session between a user and an application. AppLogics use sessions to store information about each user's interaction with the application. For example, a login AppLogic might create a session object to store the user's login name and password. This session data is then available to other AppLogics in the application.
Session data is stored in a distributed state layer in the iPlanet Application Server, so that the data is available even when the server destroys the AppLogic when it has finished executing. Storing the session data in the distributed state layer also enables AppLogics running in different clusters or servers to access the data.
A session has the following attributes, which are set when the AppLogic creates a session:
A unique ID. You can specify an ID, or use the default ID the system generates.
The ISession2 interface defines methods for setting and retrieving data in a session. It also defines methods for retrieving the attributes—ID, associated application, timeout value, and scope—of a session.An association with an application. This setting enables the iPlanet Application Server to determine which AppLogics have access to the session data.
A timeout value. You can specify if the session is automatically destroyed after a specified time. If you don't specify a timeout value (timeout = 0), the session is destroyed when you call the destroySession( ) method in the AppLogic class.
Scope. You can specify if the session data is available at the local, cluster, or enterprise-wide level.
To create an instance of the ISession2 interface, use the createSession( ) method in the AppLogic class.
If your application requires a custom session object, for example, to support additional methods, you can subclass the Session2 class (deprecated) and define your own methods.
Method
Description
Returns the name of the application associated with the session.
Returns the flags associated with the session when it was created.
Returns the name of the application associated with the session.
Syntax
public String getSessionApp()
Usage
Use getSessionApp( ) to retrieve the name of the application associated with the session. All AppLogics in an application have access to the same session data.
Return Value
A string representing the application name, or null for failure.
Example
The following code shows how to create a session and get the name of the application associated with the session://Create a session and associate it with myApp application
sess=createSession(GXSESSION.GXSESSION_DISTRIB,
//Get the application name associated with the session
//getSessionApp() should return "myApp"
appname = sess.getSessionApp();
return result("getSessionApp returned error");
log("Session application name:" + appname);
Related Topics
createSession( ) in the AppLogic class
Syntax
public IValList getSessionData()
Usage
Use getSessionData( ) to retrieve session data for processing. Data is returned in an IValList object. This method retrieves the contents that were last saved in the distributed store with saveSession( ). Use methods in the IValList interface to iterate through and access items in the IValList object.
Return Value
IValList object containing the session information, or null for failure.
Example
public class OBSession extends Objectprotected ISession2 systemSession;
public IValList sessionValList = null;
public OBSession(ISession2 app_session)
sessionValList = systemSession.getSessionData();
// Method for retrieving the user name from session data
return sessionValList.getValString("userName");
Related Topics
createSession( ) in the AppLogic class
Returns the flags associated with the session when it was created.
Syntax
public int getSessionFlags()
Usage
Use getSessionFlags( ) to retrieve the flags that were specified when the session was created with createSession( ). The following table describes the valid session flags, which are static variables in the GXSESSION class:
Flag
Description
The session is visible to all AppLogics in the enterprise environment.
The session expires n seconds from the time the node was created.
Return Value
The flags listed in the previous table.
Example
The following code shows how to create a session and get the associated flags://Create a session with distributed scope
sess=createSession(GXSESSION.GXSESSION_DISTRIB,
//Get the flag assigned to the session
//getSessionFlag() should return GXSESSION_DISTRIB
flag = sess.getSessionFlags();
Related Topics
createSession( ) in the AppLogic class
Syntax
public String getSessionID()
Usage
Use getSessionID( ) to retrieve the unique ID associated with a session.
Return Value
A string representing the session ID, or null for failure.
Example
The following code shows how to create a session and get the session ID://Create a session using the default ID generator
sess=createSession(GXSESSION.GXSESSION_DISTRIB,
return result("getSessionID returned error");
Related Topics
createSession( ) in the AppLogic class
Returns the session's timeout value in seconds.
Syntax
public int getSessionTimeout()
Usage
Use getSessionTimeout( ) to find out if a session is terminated after a specified time, or if it needs to be terminated explicitly. A timeout value of 0 means the session ends when it is explicitly terminated with the destroySession( ) method.
Return Value
Integer representing the timeout value in seconds.
Example
The following code shows how to create a session and get session's timeout value://Create a session with no timeout value
sess=createSession(GXSESSION.GXSESSION_DISTRIB,
//getSessionTimeout() should return 0
timeout = sess.getSessionTimeout();
log("Session timeout value:" + timeout);
Related Topics
createSession( ) in the AppLogic class
Syntax
public int saveSession(
int dwFlags)
Usage
Use saveSession( ) to ensure changes are saved in the distributed state storage area, which stores the session information for subsequent use if any other AppLogic objects are invoked within the same session.The AppLogic needs to call the saveSession( ) method in the AppLogic class at least once to set a cookie, which passes the session ID between the Web browser and iPlanet Application Server. The saveSession( ) method in the ISession2 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 with setSessionData( ) or after modifying the IValList returned by getSessionData( ).
To improve performance, keep smaller amounts of information in the session.
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
createSession( ) and saveSession( ) in the AppLogic class
Updates session with specified data.
Syntax
public int setSessionData(
IValList pSessionData)pSessionData. The IValList object containing the session data to set.
Usage
Use setSessionData( ) to write or update session data. Session data is stored in a distributed state layer in the iPlanet Application Server, making session data accessible to distributed server processes.The AppLogic should call saveSession( ) to save changes after updating session data with setSessionData( ).
To improve performance, keep smaller amounts of information in the session.
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
createSession( ) in the AppLogic class
ISessionIDGen Interface (deprecated)
The ISessionIDGen interface is deprecated and is provided for backward compatibility only. New applications should use the interface javax.servlet.http.HttpSession and the servlet programming model.
The ISessionIDGen interface represents a session ID generator. The session-related methods in the AppLogic class take an ISessionIDGen object as a parameter. By default, iPlanet Application Server uses the ISessionIDGen object to generate a session ID when an AppLogic creates a new session with the createSession( ) method in the AppLogic class.
The session ID—based on a 64-bit number—uniquely identifies a session between a user and an application. In a Web-based application, session IDs are passed between the Web browser and iPlanet Application Server to verify user sessions as users traverse the application. For non-browser clients, session IDs are tracked on the server.
Related Topics
createSession( ) and getSession( ) in the AppLogic class (deprecated)ISession2 Interface (deprecated)
The IState2 interface represents a node, or state object, in the State tree. A state tree is a hierarchical data storage mechanism. It is used primarily for storing application data that needs to be distributed across server processes and clusters. For example, the session data your application creates and maintains is stored in nodes of a state tree.
Use a state tree in your application if it needs to maintain and share data in a multi-server environment running load-balanced application components. A node has the following attributes:
A name. Nodes on the same level of the state tree must have unique names, but not otherwise.
The IState2 interface defines methods for creating and deleting nodes, setting and retrieving node contents, and retrieving the attributes of a node.Contents in the form of an IValList.
A timeout value. You can specify if the content of the node automatically expires after a specified time. If you don't specify a timeout value (timeout = 0), the content is saved until the node is deleted explicitly.
Scope. You can specify if the node data is available at the local, cluster, or enterprise-wide level.
To create a state tree, use the following methods:
getStateTreeRoot( ) method in the AppLogic class to create the root node.
createStateChild( ) in this interface to create the child nodes.
Method
Description
Creates a child node under the node on which this method is called.
Creates a child node under the node on which this method is called.
Syntax
public IState2 createStateChild(
String pName,
int Timeout,
int dwFlags)pName. The name of the child node. If a child node with the given name already exists, this method returns an error.
Timeout. The unit of timeout is seconds. The meaning of timeout depends on the timeout flag specified in dwFlags. A value of 0 means the contents of the node is saved until deleted explicitly. You can assign a non-zero timeout value only to child nodes that are leaf nodes. Parent nodes can only have a timeout value of 0.
dwFlags. Specify one of the following flags, or 0 to use the default system settings:
GXSTATE.GXSTATE_LOCAL to make the node visible to the local process only.
The default scope is distributed and the default timeout is 60 seconds from the time the node was last accessed.GXSTATE.GXSTATE_CLUSTER to make the node visible to all application components within the cluster.
GXSTATE.GXSTATE_DISTRIB to make the node visible to all application components in the enterprise environment.
GXSTATE.GXSTATE_TIMEOUT_CREATE to specify that the contents of the node expires n seconds from the time the node was created.
Usage
Use createStateChild( ) to add a child node to a state tree. The application component should already have created the root node of the tree with getStateTreeRoot( ) in the AppLogic class.To create a new child node in a particular position of the tree, traverse the tree until you reach the node that will be the parent of the new child node. Then call createStateChild( ).
The scope of a parent node must be the same as or greater than the scope of its child nodes. For example, if the scope of a child node is set to the cluster level, its parent node must be set to either the cluster or distributed level.
Tips
To traverse the state tree to find the desired location in which to create a new child node, use getStateChild( ). Each successive call to getStateChild( ) descends one level in the tree.
Return Value
An IState2 object, or null for failure.
Example
The following code shows how to create a child node if it doesn't already exist:IState2 tree = getStateTreeRoot(GXSTATE.GXSTATE_DISTRIB, "Grammy");
IState2 child = tree.getStateChild("Best Female Vocal");
child = tree.createStateChild("Best Female Vocal", 0,
Deletes a child node from a state tree.
Syntax
public int deleteStateChild(
String pName)pName. The name of the child node to delete.
Usage
Use deleteStateChild( ) to delete a child node from a state tree when your application no longer needs it. A child node can be deleted only from its parent node. For example, if the state tree has three levels and you want to delete a node at the third level, traverse the tree until you find its parent node at the second level. Then call deleteStateChild( ) to delete a specific node
Rule
You can delete a parent node only after deleting its child nodes.
Tip
To traverse the state tree to find the parent node of the child node to delete, use getStateChild( ). Each successive call to getStateChild( ) descends one level in the tree.
Return Value
GXE.SUCCESS if the method succeeds.
Syntax
public IState2 getStateChild(
String pName)pName. The name of the child node to get.
Usage
Use getStateChild( ) to retrieve a node whose content you want to get or update. Your application component can also use getStateChild( ) to traverse a state tree to find the parent node of child nodes to add or delete.
Return Value
An IState2 object, or null for failure.
Gets the count of children nodes.
Syntax
public int getStateChildCount(
int dwFlags) // parameter is currently unused.
Usage
Use this method to return the number of children at any given state node.
Return Value
An integer representing the number of children.
Gets the contents of the node.
Syntax
public IValList getStateContents()
Usage
Use getStateContents( ) to retrieve the contents of the node, or to check if the node contains contents before setting values in the node. This method retrieves the contents that were last saved in the distributed store with saveState( ).To traverse the state tree to find a specific node, use getStateChild( ). Each successive call to getStateChild( ) descends one level in the tree.
If you update the contents of a node with setStateContents( ) but do not save the contents in the distributed store with saveState( ), getStateContents( ) will not return the content set with setStateContents( ). It will return the contents that were last saved.
Return Value
An IValList object that contains the contents, or null for failure.
Gets the flags assigned to the node when it was created.
Syntax
public int getStateFlags()
Usage
Use getStateFlags( ) to retrieve the flag that represents the node's scope, lifetime, and timeout criteria. This flag is specified when the state node is created. The following table describes the valid session flags, which are static variables in the GXSTATE class:
Return Value
One of the flags listed in the previous table.
Syntax
public String getStateName()
Usage
Use getStateName( ) when the name of the node is unknown and is required for subsequent operations.
Return Value
A string value representing the name of the current node.Returns the node's timeout value in seconds.
Syntax
public int getStateTimeout()
Usage
Use getStateTimeout( ) in conjunction with getStateFlags( ) to determine if and when the contents of the node expires. A timeout value of 0 means the node contents are saved until the node is deleted explicitly.
Return Value
Integer representing the timeout value in seconds.Saves updates to the node contents.
Syntax
public int saveState(
int dwFlags)dwFlags. Specify 0 (zero). Internal use only.
Usage
Use saveState( ) after you set or change the contents of a node. This method flushes the node contents into the distributed store.
Tip
The getStateContents( ) method retrieves the contents that were last saved in the distributed store with saveState( ). Therefore, if you update the contents of a node with setStateContents( ), but do not call saveState( ), getStateContents( ) will not return the content set with setStateContents( ).
Return Value
GXE.SUCCESS if the method succeeds.
Syntax
public int setStateContents(
IValList pContents)pContents. IValList of values to set in the current node.
Usage
Use setStateContents( ) to update the contents of a node.To traverse the state tree to find the child node to update, use getStateChild( ). Each successive call to getStateChild( ) descends one level in the tree.
Call saveState( ) after you set or change the contents of a node. This method flushes the node contents into the distributed store. If you call setStateContents( ) several times before calling saveState( ), only the value from the last setStateContents( ) call is saved.
The getStateContents( ) method retrieves the contents that were last saved in the distributed store with saveState( ). Therefore, if you update the contents of a node with setStateContents( ), but do not call saveState( ), getStateContents( ) will not return the content set with setStateContents( ).
Return Value
GXE.SUCCESS if the method succeeds.
Example
The following code shows how to create a child node and set its contents:
IStreamBuffer Interface (deprecated)
The IStreamBuffer interface is deprecated and is provided for backward compatibility only. New applications developed according to the servlet-JSP programming model do not need the functionality provided by the IStreamBuffer interface.
The IStreamBuffer interface represents a buffer for capturing streamed output during template processing. Use a stream buffer if your AppLogic needs to manipulate the data before sending it to another AppLogic. For example, the AppLogic can collect the data in a stream buffer, then parse it or save it to a file.
To capture the data in a stream buffer, use the evalOutput( ) method in the AppLogic class and pass in an IStream object. To manipulate the data in the stream buffer, use the getStreamData( ) method in this interface.
To create an instance of the IStreamBuffer interface, use the GX.CreateStreamBuffer( ) method.
Returns an array of byte values from the stream buffer.
Syntax
public byte[] getStreamData(
int flags)
Usage
Use getStreamData( ) to retrieve the contents of the stream buffer that was captured during streamed template processing. The AppLogic can then manipulate the data as needed.
Rule
Call getStreamData( ) after evalOutput( ) in the AppLogic class. The evalOutput( ) method captures output in the stream buffer if the AppLogic passes in an IStream object.
Return Value
Array of byte values, or null for failure.
Related Topics
evalOutput( ) in the AppLogic class (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:
Add, update, and delete rows in the table.
The ITable interface is part of the Data Access Engine (DAE) service.Obtain information about table attributes as they are defined in the database catalog. Table attributes include the table name, table columns, data connection, and so on. To obtain additional information about individual columns, use the methods in the IColumn Interface (deprecated).
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.
Example
// Add a new user to the User tableITable tbl = conn.getTable("CTLuser");
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);
return result(valOut, "User added");
return result(valOut, "Failed to add the user");
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:
For synchronous operations, the default, specify zero or GX_DA_EXECUTEQUERY_FLAGS.GX_DA_EXEC_SYNC.
For asynchronous operations, specify GX_DA_EXECUTEQUERY_FLAGS.GX_DA_EXEC_ASYNC.
pTrans. ITransobject that contains the transaction associated with this insert operation, or null.
Usage
Use addRow( ) to insert a new record into a table.Before adding a row, the AppLogic must first call allocRow( ) to create a row buffer.
Next, the AppLogic must specify data values for the new row by calling any of the setValueXXX( ) methods, such as setValueString( ) or setValueBinary( ).
The AppLogic must specify a value for any column defined as NOT NULL and without a DEFAULT value, such as keys.
The AppLogic must be logged into the database with sufficient privileges to insert records in the target table.
If the insert operation is part of a transaction, the AppLogic must first create an instance of the ITrans Interface (deprecated) using createTrans( ) in the AppLogic class (deprecated). The AppLogic must then call begin( ) before executing the statement and, after executing the statement, call commit( ) or rollback( ) as appropriate.
Tips
To determine whether a column is defined as NOT NULL, use getNullsAllowed( ) in the IColumn Interface (deprecated).
Alternatively, the AppLogic can insert records by passing a SQL INSERT statement using setSQL( ) in the IQuery Interface (deprecated). The statement must comply with ANSI 92 SQL syntax.
Return Value
An int value indicating success (zero) or failure (non-zero, such as an invalid transaction object).ITable table = conn.getTable("OBTransaction");
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");
ITrans transferTrans = createTrans();
return handleOBSystemError("Could not start transaction");
// Allocate row in table for new entry
table.setValueString(acctNumCol, fromAcct);
table.setValueInt(transTypeCol, OBDBDefs.TRANSTYPE_WITHDRAWAL);
table.setValueDateString(postDateCol, transDateString);
table.setValueDouble(amountCol, amount.doubleValue() * -1.0);
rc = table.addRow(0, transferTrans);
Related Topics
ITrans Interface (deprecated)
Allocates a new, empty row buffer, replacing the previous row buffer if one exists.
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( ).The AppLogic must call allocRow( ) before specifying column values with a setValueXXX( ) method.
The AppLogic must call allocRow( ) every time before calling addRow( ) or updateRow( ).
Return Value
GXE.SUCCESS if the method succeeds.ITable table = conn.getTable("OBTransaction");
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");
ITrans transferTrans = createTrans();
return handleOBSystemError("Could not start transaction");
// Allocate row in table for new entry
table.setValueString(acctNumCol, fromAcct);
table.setValueInt(transTypeCol, OBDBDefs.TRANSTYPE_WITHDRAWAL);
table.setValueDateString(postDateCol, transDateString);
table.setValueDouble(amountCol, amount.doubleValue() * -1.0);
rc = table.addRow(0, transferTrans);
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:
For synchronous operations, the default, specify zero or GX_DA_EXECUTEQUERY_FLAGS.GX_DA_EXEC_SYNC.
For asynchronous operations, specify GX_DA_EXECUTEQUERY_FLAGS.GX_DA_EXEC_ASYNC.
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.
The AppLogic must be logged into the database with sufficient privileges to delete records in the target table.
If the delete operation is part of a transaction, the AppLogic must first create an instance of the ITrans Interface (deprecated) using createTrans( ) in the AppLogic class (deprecated). The AppLogic must then call begin( ) before executing the statement and, after executing the statement, call commit( ) or rollback( ) as appropriate.
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");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)
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.ITable tbl = conn.getTable("Products");
htmlString += "<h2>Products Table</h2>";
while ((col = tbl.enumColumns()) != null) {
htmlString += "Column Name = ";
htmlString += ", Column Type = ";
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.
The columns might not be returned in the order in which they are defined in the database catalog.
Test for null to determine when the last column has been retrieved.
Return Value
IColumn object containing the next column of data, or null for failure (such as no more columns in the table).ITable tbl = conn.getTable("Products");
htmlString += "<h2>Products Table</h2>";
while ((col = tbl.enumColumns()) != null) {
htmlString += "Column Name = ";
htmlString += ", Column Type = ";
Related Topics
IColumn Interface (deprecated)
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");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)
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.Column positions in a table may change between different table objects.
Columns are not guaranteed to be in the same order in which the database lists them.
To iterate through columns in a table using getColumnByOrd( ), call getNumColumns( ) to determine the maximum number of columns in the table, then proceed sequentially through each column using getColumnByOrd( ), beginning with column 1, through the last column.
Alternatively, call enumColumnReset( ) to start with the first column in the table, then call enumColumns( ) repeatedly through the last column.
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 tableITable tbl = conn.getTable("Products");
int maxCols = tbl.getNumColumns();
IColumn col = tbl.getColumnByOrd(i);
. . . manipulate column using IColumn methods . . .
Related Topics
IColumn Interface (deprecated)
Returns the ordinal position of the column specified by name.
Syntax
public int getColumnOrdinal(
String szColumn)
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.ITable table = conn.getTable("OBTransaction");
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)
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)
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).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 tableITable tbl = conn.getTable("Products");
int maxCols = tbl.getNumColumns();
IColumn col = tbl.getColumnByOrd(i);
. . . manipulate column using IColumn methods . . .
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.The AppLogic must call allocRow( ) before attempting to write to the row buffer.
The data type of the column must be BINARY or VARBINARY, or database equivalent.
Tip
Use setValueBinaryPiece( ) for LONGBINARY, LONGVARBINARY, or equivalent type values.
Return Value
GXE.SUCCESS if the method succeeds.
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.The AppLogic must call allocRow( ) before attempting to write to the row buffer.
The data type of the column must be LONGBINARY, LONGVARBINARY, or database equivalent.
Must be called after allocRow( ) but before addRow( ) or updateRow( ).
Tip
Use setValueBinary( ) for BINARY, VARBINARY, or equivalent type values.
Return Value
GXE.SUCCESS if the method succeeds.
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:
"Fri Oct 10 14:35:59.999 PDT 1997"
"1997-10-01 14:35:59.999"
- The subseconds (,999 in the example) and time zone (PDT in the example) are optional.
- The time is optional.
Rule
The AppLogic must call allocRow( ) before attempting to write to the row buffer.
Return Value
GXE.SUCCESS if the method succeeds.ITable table = conn.getTable("OBTransaction");
return handleOBSystemError("Could not access table OBTransactionType.");
int postDateCol = table.getColumnOrdinal("postDate");
// Allocate a new row and set a datestring value
table.setValueDateString(postDateCol, transDateString);
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.ITable table = conn.getTable("OBTransaction");
return handleOBSystemError("Could not access table
int amountCol = table.getColumnOrdinal("amount");
// Allocate a new row and set a double value
table.setValueDouble(amountCol, amount.doubleValue() * -1.0);
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.ITable table = conn.getTable("OBTransaction");
return handleOBSystemError("Could not access table
int transTypeCol = table.getColumnOrdinal("transType");
// Allocate a new row and set an Int value
table.setValueInt(transTypeCol, OBDBDefs.TRANSTYPE_WITHDRAWAL);
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.ITable table = conn.getTable("OBTransaction");
return handleOBSystemError("Could not access table
int acctNumCol = table.getColumnOrdinal("acctNum");
// Allocate a new row and set a string value
table.setValueString(acctNumCol, fromAcct);
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.The AppLogic must call allocRow( ) before attempting to write to the row buffer.
The data type of the column must be TEXT or database equivalent.
Tip
Use setValueTextPiece( ) for LONGTEXT or equivalent type values.
Return Value
GXE.SUCCESS if the method succeeds.
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.The AppLogic must call allocRow( ) before attempting to write to the row buffer.
The data type of the column must be LONGTEXT or database equivalent.
Tip
Use setValueText( ) for TEXT or equivalent type values.
Return Value
GXE.SUCCESS if the method succeeds.
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:
For synchronous operations, the default, specify zero or GX_DA_EXECUTEQUERY_FLAGS.GX_DA_EXEC_SYNC.
For asynchronous operations, specify GX_DA_EXECUTEQUERY_FLAGS.GX_DA_EXEC_ASYNC.
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.
Before modifying a row, the AppLogic must first call allocRow( ) to create the row buffer.
Next, the AppLogic must specify data values for the new row by calling any of the following methods: setValueDateString( ), setValueDouble( ), setValueInt( ) , or setValueString( ).
For tables defined with one or more UNIQUE keys, the AppLogic can perform a single-record update but not a multiple-record update.
The AppLogic must specify a value for any column defined as NOT NULL and without a DEFAULT value, such as keys.
The AppLogic must be logged into the database with sufficient privileges to update records in the target table.
If the update operation is part of a transaction, the AppLogic must first create an instance of the ITrans Interface (deprecated) using createTrans( ) in the AppLogic class (deprecated). The AppLogic must then call begin( ) before executing the statement and, after executing the statement, call commit( ) or rollback( ) as appropriate.
Tips
The updateRow( ) method overwrites all columns in the target record(s) with the contents of the row buffer. Therefore, retrieve the row first using a query, assign the column values to the row buffer, then change only the column(s) you want to update.
To determine whether a column is defined as NOT NULL, use getNullsAllowed( ) in the IColumn Interface (deprecated).
Alternatively, the AppLogic can update records by passing a SQL INSERT statement using setSQL( ) in the IQuery Interface (deprecated). The statement must comply with ANSI 92 SQL syntax.
Return Value
GXE.SUCCESS if the method succeeds.
Example
// Obtain the definition for the Catalog tableITable tbl=conn.getTable("CTLcatalog");
return result("Cannot find table: "+"CTLcatalog");
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*cReor der)
return result("Cannot map columns on table:
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);
valIn.setValString("productId", prodStr);
tbl.setValueInt(cProductId, productId);
tbl.updateRow(0, "productId"+"="+prodStr, null);
Related Topics
ITrans Interface (deprecated)
ITemplateData Interface (deprecated)
ITemplateData is deprecated and is provided for backward compatibility only. New Java applications should use the standard servlet-JSP programming model, where similar functionality is provided through interfaces such as java.sql.ResultSet and javax.sql.RowSet.
For information about replacing ITemplateData functionality in existing applications, see the Migration Guide.
The ITemplateData interface represents a hierarchical source of data used for HTML template processing. ITemplateData provides methods for iterating through rows in a set of memory-based hierarchical data and retrieving column values.
To create an ITemplateData object, an AppLogic calls GX.CreateTemplateDataBasic( ). The AppLogic populates the ITemplateData object with rows of hierarchical data, then passes this ITemplateDataBasicobject as the data parameter in evalTemplate( ) or evalOutput( ) in the AppLogic class (deprecated). The Template Engine then draws upon the hierarchical data during template processing using methods in the ITemplateData interface.
The Template Engine normally processes the hierarchical template data internally. To provide application-specific special processing and hook into the template generation process, the AppLogic can subclass the TemplateDataBasic class (deprecated) and override the ITemplateData member methods.
Example
// Determine whether AppLogic module is listed in projectname = tdb.getValue("MODULENAME");
(name.compareTo(moduleName) == 0)) {
GenerateReport("The AppLogic already exists.<br>"
+"Please choose another name.", null, null);
while (tdb.moveNext("MODULE") == 0);
Related Topics
evalTemplate( ) and evalOutput( ) in the AppLogic class (deprecated)TemplateDataBasic class (deprecated)
The Template Engine calls this method to dynamically retrieve the value of the specified field from the current row in the hierarchical template data.
Syntax
public IBuffer getValue(
String szExpr)szExpr. Name of a field in the template data object.
Usage
The Template Engine calls getValue( ) to retrieve values from the hierarchical template data object for subsequent processing.
Rule
The specified field name must exist in the template data object.When processing result sets, first call isEmpty( ) to determine whether rows were returned. Next, for each row in the result set, call getValue( ) to retrieve field values, then call moveNext( ) to move to the next row in the result set, until the end of the result set is reached.
Use methods in the IBuffer interface to manipulate the returned memory block.
Use Util.toString( ) to convert the contents of the returned memory buffer into a String.
Return Value
An IBuffer object that contains the value of the specified field name, or null for failure (such as invalid field name).
Related Topics
evalTemplate( ) and evalOutput( ) in the AppLogic class (deprecated)TemplateDataBasic class (deprecated)
The Template Engine calls this method to determine whether the specified group in the hierarchical result set is empty (contains no rows).
Syntax
public boolean isEmpty(
String group)group. Name of a group in the hierarchical result set.
Usage
The Template Engine calls isEmpty( ) to test whether the specified group in the ITemplateData object contains any rows of data before processing individual fields using getValue( ).
Rule
The specified group name must exist in the hierarchical data set.
Tip
When processing result sets, first call isEmpty( ) to determine whether rows were returned. Next, for each row in the result set, call getValue( ) to retrieve field values, then call moveNext( ) to move to the next row in the result set, until the end of the result set is reached.
Return Value
True if the specified group is empty, and false if it contains rows of data or if the specified group name is invalid.
Related Topics
evalTemplate( ) and evalOutput( ) in the AppLogic class (deprecated)TemplateDataBasic class (deprecated)
The Template Engine calls this method to retrieve the next row of the specified group in the hierarchical template data object.
Syntax
public int moveNext(
String group)group. Name of a group to process in the hierarchical data of the template data object.
Usage
The Template Engine calls moveNext( ) when iterating through rows in the template data object to retrieve the contents of the next sequential hierarchical row of data.
Rule
The specified group name must exist in the hierarchical data set.
Tip
When processing result sets, first call isEmpty( ) to determine whether rows were returned. Next, for each row in the result set, call getValue( ) to retrieve field values, then call moveNext( ) to move to the next row in the result set, until the end of the result set is reached.
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
evalTemplate( ) and evalOutput( ) in the AppLogic class (deprecated)TemplateDataBasic class (deprecated)
The setHint( ) method is a placeholder for future functionality. Currently, it is implemented to return 0. If you create a custom template data class that implements the ITemplateData interface, implement setHint( ) to return 0.
Syntax
public int setHint(
String group,
int flags,
int max,
IValList pVal)
ITemplateMap Interface (deprecated)
ITemplateMap is deprecated and is provided for backward compatibility only. New Java applications should use the standard servlet-JSP programming model.
For information about replacing ITemplateMap functionality in existing applications, see the Migration Guide.
The ITemplateMap interface represents a mapping between a template field specification and dynamic data used for HTML template processing. ITemplateMap provides the get( ) method for resolving the id attribute in a GX markup tag. Each id attribute contains a field name that can be mapped.
To create a field map, an AppLogic calls GX.CreateTemplateMapBasic( ). The AppLogic then populates the field map using put( ), in the TemplateMapBasic class (deprecated), for each field mapping, then passes this ITemplateMap object as the map parameter in evalTemplate( ) or evalOutput( ) in the AppLogic class (deprecated). When the Template Engine encounters a GX markup tag with the id attribute while processing the template, it calls get( ) in the ITemplateMap Interface (deprecated) to resolve the name. The get( ) method, in turn, calls getString( ) in the TemplateMapBasic class (deprecated) to actually resolve the name.
To provide application-specific special processing, an AppLogic can subclass the TemplateMapBasic class (deprecated) and override the getString( ) method to hook into the Template Engine generation process. For example, the AppLogic can intercept and filter data from a database before the Template Engine processes it.
Resolves the id attribute specified in a GX markup tag in the template being processed by the Template Engine. This method is called by the Template Engine.
Related Topics
evalTemplate( ) and evalOutput( ) in the AppLogic class (deprecated)TemplateMapBasic class (deprecated)
ITemplateData Interface (deprecated)
TemplateDataBasic class (deprecated)
Resolves the id attribute specified in a GX markup tag in the template being processed by the Template Engine. This method is called by the Template Engine.
Syntax
public IBuffer get(
String szExpr,
IObject pData,
IObject pMark)szExpr. In the current GX markup tag in the HTML template being processed, the name of the field, or placeholder, assigned to the id attribute. Must be an identical match (case-sensitive).
pData. Specify null. Internal use only.
pMark. Specify null. Internal use only.
Usage
GX markup tags are used in an HTML template to identify where dynamic data appears in the output report. In the GX markup tags, the id attribute specifies any of the following items: the name of a flat query within a hierarchical query, a field in the hierarchical result set or TemplateDataBasic object, or an HTML template. The type of item specified in the id attribute depends on the type attribute that is specified in the same GX markup tag.The Template Engine calls get( ) to resolve theid attribute specified in a GX markup tag in the template being processed by the Template Engine. The get( ) method, in turn, calls getString( ) in the TemplateMapBasic class (deprecated) to actually resolve the name. To provide application-specific special processing, an AppLogic can subclass the TemplateMapBasic class (deprecated) and override getString( ) to manipulate the Template Engine generation process. For example, an AppLogic can intercept and filter data from a database before the Template Engine processes it.
Return Value
An IBuffer object that contains the value of the id mapping, or null for failure.
Related Topics
evalTemplate( ) and evalOutput( ) in the AppLogic class (deprecated)getString( ) in theTemplateMapBasic class (deprecated)
ITemplateData Interface (deprecated)
TemplateDataBasic class (deprecated)
ITile is deprecated and is provided for backward compatibility only. New Java applications should use the standard servlet-JSP programming model.
For information about replacing ITile functionality in existing applications, see the Migration Guide.
The ITile interface represents a tile, which is a record set that contains multiple records. A tile can also contain nested tiles. Organized like a hierarchical result set, a tile is returned by the GX.ProcessOutput( ) method.
AppLogics use ITile together with GX.ProcessOutput( ) when working with non-HTML results returned by another AppLogic. The following are the general steps for getting the tile:
A client AppLogic calls an AppLogic with newRequest( ).
The tile corresponds to the structure specified by the tile and cell tags in the template file that the called AppLogic used when it called evalOutput( ). The tile tag determines the tile or record set, and the cell tag, the values in each record.Through newRequest( ), the client passes input and output IValLists to the called AppLogic. If the client is an AppLogic, it specifies the value "ocl" for the gx_client_type key in the input IValList.
The called AppLogic processes the request and sends back results using its output IValList or by calling evalOutput( ).
The client calls the GX.ProcessOutput( ) method to process the results into an ITile object.
Using methods in the ITile interface, the client traverses the tile and retrieves values to populate user interface controls, such as text boxes or list boxes, on a form.
Example
The following example shows a template file used by a called AppLogic when generating output, and a section of a program that uses GX.ProcessOutput( ) and ITile methods to process the output:<gx type=tile id="PRODUCTS" max=100>
<gx type=cell id="PRODUCTS.Category"></gx>
<gx type=cell id="PRODUCTS.ProdName"></gx>
<gx type=tile id="CATEGORIES" max=100>
<gx type=cell id="CATEGORIES.CategoryId"></gx>
hr = Conn.newRequest(guid, vIn, vOut, 0);
// Get the root tile from the output vallist
ITile roottile = GX.ProcessOutput(null, 0, vOut);
//Iterate over all products and print their names
ptile = roottile.getTileChild("PRODUCTS");
System.out.println("Products:");
while (ptile != null && hr != GXE.FAIL)
sval = ptile.getTileValue("PRODUCTS.ProdName");
System.out.println(" " + sval);
hr = ptile.moveTileNextRecord();
//Iterate over all categories and print their ids
ptile = roottile.getTileChild("CATEGORIES");
System.out.println("Categories:");
while (ptile != null && hr != GXE.FAIL)
sval = ptile.getTileValue("CATEGORIES.CategoryId");
System.out.println(" " + sval);
hr = ptile.moveTileNextRecord();
Related Topics
newRequest( ) and evalOutput( ) in the AppLogic class (deprecated)GX.ProcessOutput( ),
IValList Interface (deprecated)
Syntax
public ITile getTileChild(
String name)name. The name of the child tile in the tile. This name must match a name assigned to the id attribute of type tile in the template file.
Usage
Use getTileChild( ) to retrieve a tile from which to get records and record values. Use it in conjunction with moveTileNextRecord( ) and getTileValue( ) to traverse the tile and retrieve record values. The client can call these methods in a loop until all values in a tile have been retrieved.
Return Value
An ITile object, or null for failure.
Related Topics
getTileValue( ),
moveTileNextRecord( )
Returns the value of a specified field in a record.
Syntax
public String getTileValue(
String name)name. The name of the field in the current record. This name must match a name assigned to the id attribute of type cell in the template file.
Usage
Use getTileValue( ) to retrieve values in a record. Use it in conjunction with getTileChild( ) and moveTileNextRecord( ) to traverse the tile and retrieve each value. The client can call these methods in a loop until all values in a tile have been retrieved.
Return Value
The record value as a string.
Related Topics
getTileChild( ),
moveTileNextRecord( )
Moves to the next record in the tile.
Syntax
public int moveTileNextRecord()
Usage
Use moveTileNextRecord( )to go to the next record in a tile after retrieving values in the current record. Use the method in conjunction with getTileChild( ) and getTileValue( ) to traverse the tile and retrieve each value. The client can call these methods in a loop until all values in a tile have been retrieved.
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
getTileChild( ),
getTileValue( )
Moves to a specific record in the tile.
Syntax
public int moveTileNextRecord(
int ord)ord. The position of the record in the tile. The first record in a tile is 1, the second is 2, and so on.
Usage
Use moveTileToRecord( ) when iterating through the tile multiple times. For example, after iterating through all the records, the AppLogic can return to the first record in preparation for the next iteration. If the tile contains many records, the AppLogic can also use moveTileToRecord( ) to display only several records at a time.
Return Value
GXE.SUCCESS if the method succeeds.
ITrans is deprecated and is provided for backward compatibility only. In new applications, either use XA transactions from the Java Transaction API (JTA), or set the appropriate autocommit mode on java.sql.Connection, an interface of the JDBC Core API.
The ITransinterface represents a transaction object used for subsequent transaction processing operations. ITrans provides operations for beginning, committing, and rolling back transactions.
After instantiating a transaction object, the AppLogic calls begin( ) to start the transaction. Next, the AppLogic performs any query, insert, update, or delete operations, passing the transaction object to the respective method in the ITable Interface (deprecated). Finally, the AppLogic closes the transaction by calling either commit( ) to save all changes or rollback( ) to cancel them. Closing a transaction terminates the transaction object and releases system resources.
The calls that make up a transaction can be in any part of the code; they need not be consecutive. The commands in a transaction are united by the fact that they all have the same transaction object as a parameter.
An application can process several transactions simultaneously. Each transaction works with a different database connection object. Within a single transaction, however, all the commands must access a single database through a single connection object.
To create an instance of the ITrans interface, use createTrans( ) in the AppLogic class (deprecated), as shown in the following example:.
Example
// Create and begin a transactionif(!processCreditCard(cusId, card, number, expirationDate, trx)) {
return result("Could not process the credit card information"); }
// 2) Process the invoice record
InfoHolder info=new InfoHolder();
if(!makeInvoiceRecord(cusId, number, trx, info)) {
return result("Could not create the invoice record"); };
// 3) Process products on the invoice
if(!makeInvoiceEntries(info.invoiceId, trx)) {
return result("Could not create the invoice product records"); };
// 4) Process optional shipping information
if(shippingInfo && !makeShippingRecord(info.invoiceId, trx, addr1, addr2, city, state, zip)) {
return result("Could not create the shipping information record"); };
// 5) Process the inventory for each purchased product
if(!reduceProductInventory(trx)) {
// Problem occurred - abandon everything
// No problem occurred - save everything
Related Topics
createTrans( ) in the AppLogic class (deprecated)addRow( ), updateRow( ), and deleteRow( ) in the ITable Interface (deprecated)
Usage
Use begin( ) to start a transaction before performing any operations in the transaction. Subsequent operations belong to the current transaction until either commit( ) or rollback( ) is called.AppLogic must start the transaction explicitly using begin( ) before performing any query, insert, update, or delete operations associated with the transaction.
AppLogic must complete the transaction explicitly by calling commit( ) to save any changes to tables or rollback( ) to abandon them. If a database error occurs before either are called, the database server will roll back the transaction automatically.
Tip
Use transactions judiciously to avoid locking conflicts. For example, avoid deadlocks by not using different open transactions on the same table.
Return Value
GXE.SUCCESS if the method succeeds.
Example
// Create a transactionITrans updCustTrans = createTrans();
return handleOBSystemError("Could not create transaction");
Related Topics
createTrans( ) in the AppLogic class (deprecated)addRow( ), updateRow( ), and deleteRow( ) in the ITable Interface (deprecated)
Commits the transaction, saving any changes.
Syntax
public IObject commit(
int dwFlags)
Usage
Use commit( ) to commit a transaction and write unsaved changes to disk. commit( ) saves the changes, terminates the transaction object, and releases system resources.The AppLogic must start the transaction explicitly by calling begin( ) before any changes associated with the transaction can be committed.
The AppLogic must complete the transaction explicitly by calling commit( ) to save any changes to tables or rollback( ) to abandon them.
The AppLogic cannot reuse an ITrans object that has been committed. It must create a new one using createTrans( ) in the AppLogic class (deprecated).
Tips
If an error occurs before the commit operation succeeds, the database server usually rolls back the transaction automatically.
The target database server may take time to process a commit request.
Return Value
IObject object (for internal use only), or null for failure.
Example
// Update Customer recordrs = updCustPQuery.execute(0, custValList, updCustTrans, null);
// Rollback transaction if the update operation failed
return handleOBSystemError("Could not update Customer.");
// Commit the transaction if the update operation succeeded
valIn.setValString("OUTPUTMESSAGE", "Successfully updated customer record.");
Related Topics
createTrans( ) in the AppLogic class (deprecated)addRow( ), updateRow( ), and deleteRow( ) in the ITable Interface (deprecated)
Rolls back the transaction, abandoning any changes.
Usage
Many database servers buffer changes made during a transaction, then update the affected tables only after the commit request is received.Rolling back a transaction terminates the transaction object and releases system resources.
The AppLogic must start the transaction explicitly by calling begin( ) before any changes associated with the transaction can be rolled back.
The AppLogic must complete the transaction explicitly by calling commit( ) to save any changes to tables or rollback( ) to abandon them.
The AppLogic cannot reuse an ITrans object that has been rolled back. It must create a new one using createTrans( ) in the AppLogic class (deprecated).
Tip
If an error occurs before the commit operation succeeds, the database server usually rolls back the transaction automatically.
Return Value
GXE.SUCCESS if the method succeeds.rs = updUserPQuery.execute(0, userValList, updCustTrans, null);
return handleOBSystemError("Could not update User.");
Related Topics
createTrans( ) in the AppLogic class (deprecated)addRow( ), updateRow( ), and deleteRow( ) in the ITable Interface (deprecated)
IValList Interface (deprecated)
IValList is deprecated and is provided for backward compatibility only. New Java applications should use the standard servlet-JSP programming model.
For information about replacing IValList functionality in existing applications, see the Migration Guide.
An IValList represents a collection of GXVAL objects. This collection is not a sequential list, but an unordered set of GXVAL objects with no implied sequence or progression.
For iPlanet Application Server-enabled AppLogics, input arguments and output value(s) are stored in IValList objects. Every request to an AppLogic passes a list of input arguments, and every result from an AppLogic returns a list of output values. The AppLogic class (deprecated) defines two member variables, valIn and valOut, to contain the input arguments and output values, respectively, of AppLogic execution.
In an IValList, values and objects are mapped to keys. The key name is the name of a GXVAL object. AppLogic code refers to GXVAL object in the IValList by its key name. Key names are unique within each IValList object.
The IValList interface provides methods for adding, retrieving, removing, and counting GXVAL objects in the IValList instance. Using methods in the IValList interface, the AppLogic can test for input arguments and modify their contents for output values.
Keys may be passed to the AppLogic as a request from an HTML document or from another AppLogic module. In an HTML form, keys are often the field names defined in the form. In this way, the AppLogic can easily identify expected, common, or "well-known" keys, and the AppLogic can ignore irrelevant parameters.
For example, an AppLogic named getLogin might prompt users for their username and login, then pass this information, identified as "username" and "password", to other AppLogics for processing. An AppLogic named validateLogin could retrieve the input parameters, find the values associated with the well-known keys "username" and "password", then take action based on the data that the user entered (testing for its existence, performing a range or length check, looking up the combination in a password table, and so on).
To create an instance of the IValList interface, use the GX.CreateValList( ) method.
Related Topics
valIn and valOut in the AppLogic class (deprecated)execute( ) in the AppLogic class (deprecated)
Returns the number of GXVAL objects in the IValList .
Usage
When the contents of an IValList are unknown, an AppLogic can iterate through each GXVAL object to test, retrieve, and update information. Use count( ) to determine the maximum number of iterations needed to go completely through the IValList.
Rule
Do not add or remove GXVAL objects to or from the IValList when iterating through the IValList.Use count( ) in conjunction with getNextKey( ) and resetPosition( ) to iterate through the IValList.
Adding or deleting GXVAL objects changes the number of objects in a IValList. Be sure to update the GXVAL object count after each add or delete operation.
Return Value
An int value representing the number of GXVal objects in the IValList, or zero for failure (such as the IValList is empty).
Example
// Obtain the contents of the shopping basketIValList basket=session.getBasketContents();
// Determine whether basket is empty
// If basket contains items, process template to show
if(evalTemplate(EMPTY_HTML, (ITemplateData) null, (ITemplateMap)
// If basket is empty, just return message
return result("Failed to Generate HTML");
Related Topics
getNextKey( )valIn and valOut in the AppLogic class (deprecated)
execute( ) in the AppLogic class (deprecated)
Retrieves the key name of the next GXVAL object in the IValList.
Syntax
public String getNextKey()
Usage
When the contents of a IValList are unknown, the AppLogic can iterate through each GXVAL object and retrieve its key name. The AppLogic can then take action based on this information, or use the key name in operations that retrieve, update, or remove GXVAL objects in the IValList list.
Rule
Do not add or remove GXVAL objects to or from the IValList when iterating through the IValList.
Tip
Use getNextKey( ) in conjunction with count( ) and resetPosition( ) to iterate through the IValList.
Return Value
String representing the next retrieved key in the IValList, or null for failure (such as if no other keys exist).
Example
// Returns the contents of the shopping basketpublic synchronized IValList getBasketContents()
IValList ret = GX.CreateValList();
// Iterate through the contents of the shopping basket
while((key=list.getNextKey())!=null)
// Obtain the product number from the item
String prod = key.substring(PROD.length(),
// Set the return IValList appropriately
ret.setVal(prod, list.getVal(key));
Related Topics
count( )execute( ) in the AppLogic class (deprecated)
Copies the specified GXVAL object from the IValList.
Syntax
public GXVAL getVal(
String pKey)pKey. Key name of the GXVAL object to copy from the IValList.
Usage
Use getVal( ) if the data type of the GXVAL object is not known. Use getValString( ) instead for string objects, getValInt( ) for integer objects, and getValBLOB( ) for BLOB objects.
Rule
The specified key name must currently exist in the IValList.
Return Value
New GXVAL object representing a copy of the GXVAL object specified by pKey, or null for failure (such as invalid keyname).
Example
// Returns the contents of the shopping basketpublic synchronized IValList getBasketContents()
IValList ret = GX.CreateValList();
// Iterate through the contents of the shopping basket
while((key=list.getNextKey())!=null)
// Obtain the product number from the item
String prod=key.substring(PROD.length(),key.length());
// Set the return IValList appropriately
ret.setVal(prod, list.getVal(key));
Related Topics
getValBLOB( ), getValInt( ), and getValString( ) in the IValList Interface (deprecated)valIn and valOut in the AppLogic class (deprecated)
execute( ) in the AppLogic class (deprecated)
Returns a specified BLOB object from the IValList.
Syntax
public byte[] getValBLOB(
String pKey)pKey. Key name of the GXVAL object that contains the BLOB value to retrieve.
Usage
Use getValBLOB( ) when the type of a GXVAL object is a BLOB, but its value is not known and needed for subsequent operations. Use getValString( ) instead for string objects and getValInt( ) for integer objects. If the type of the GXVAL object is not known, use getVal( ).
Rule
The data type must be TEXT, BINARY, VARBINARY, or database equivalent.
Return Value
A byte array for success, or null for failure.
Related Topics
getValBLOBSize( ) and setValBLOB( ) in the IValList Interface (deprecated)
Returns the size of a specified BLOB object in the IValList.
Syntax
public int getValBLOBSize(
String pKey)pKey. Key name of the GXVAL object that contains the BLOB.
Usage
BLOB objects can be large. If you want to determine the size of a BLOB object before retrieving it, use getValBLOBSize( ).
Rule
The data type must be TEXT, BINARY, VARBINARY, or database equivalent.
Return Value
An integer value for success, or zero for failure (such as datatype mismatch).
Related Topics
getValBLOB( )
Gets the specified GXVAL object from the IValList.
Syntax
public GXVAL getValByRef(
string pKey)pKey. Key name of the GXVAL object to get from the IValList.
Usage
Use getValByRef( ) if the data type of the GXVAL object is not known, or if iterating through an IValList to get each GXVAL object. Use getValString( ) instead for string objects, getValInt( ) for integer objects, and getValBLOB( ) for BLOB objects.
Return Value
New GXVAL object representing a copy of the GXVAL object specified by pKey, or null for failure (such as invalid keyname).
Related Topics
getValBLOB( ), getValInt( ), and getValString( ) in the IValList Interface (deprecated)valIn and valOut in the AppLogic class (deprecated)
execute( ) in the AppLogic class (deprecated)
Retrieves an integer value from the specified GXVAL object in the IValList.
Syntax
public int getValInt(
String pKey)pKey. Key name of the GXVAL object from which to retrieve the integer value.
Usage
Use getValInt( ) if the data type of the GXVAL object is known to be an integer. Otherwise, use getValString( ) instead for string objects, getValBLOB( ) for BLOB objects, or getVal( ) for objects of other types.The specified key name must currently exist in the IValList.
The data type of the specified GXVAL object must map to the enum value GXVT_I4.
Return Value
An int value representing the value of the specified GXVAL object, or null for failure (such as invalid key name or data type mismatch).
Example
// Obtains the User ID from the Session's IValListreturn getValList().getValInt("UserId");
Related Topics
valIn and valOut in the AppLogic class (deprecated)execute( ) in the AppLogic class (deprecated)
Retrieves a string value from the specified GXVAL object in the IValList.
Syntax
public String getValString(
String pKey)pKey. Key name of the GXVAL object from which to retrieve the string value.
Usage
Use getValString( ) when the data type of the GXVAL object is known to be a string. Otherwise, use getValInt( ) instead for integer objects, getValBLOB( ) for BLOB objects, or getVal( ) for objects of other types.The specified key name must currently exist in the IValList.
The data type of the specified GXVAL object must map to the enum value GXVT_LPSTR.
Tips
An AppLogic can manipulate this retrieved value using member methods in the String class in the java.lang package.
Return Value
A String representing the value of the GXVAL object, or null for failure (such as invalid key name or data type mismatch).
Example
// Obtain security information from the valIn IValListString nameParm = valIn.getValString("username");
String passwordParm = valIn.getValString("password");
String aclStr = valIn.getValString("accessControlLevel");
// Obtain the credit card info from the form
String cardStr=valIn.getValString("CreditCard");
String number=valIn.getValString("CreditCardNumber");
String month=valIn.getValString("ExpireMonth");
String year=valIn.getValString("ExpireYear");
Related Topics
valIn and valOut in the AppLogic class (deprecated)execute( ) in the AppLogic class (deprecated)
Removes the specified GXVAL object from the IValList.
Syntax
public int removeVal(
String pKey)pKey. Key name of the GXVAL object to remove from the IValList.
Usage
Use removeVal( ) to delete a GXVAL object that is no longer needed in the IValList . For example, if the AppLogic contains overloaded methods, you might want to remove a GXVAL object to ensure that the proper method is executed.The specified key name must currently exist in the IValList.
Do not remove GXVAL objects from the IValList when iterating through the IValList.
Return Value
GXE.SUCCESS if the method succeeds.
Example
// Empties the contents of the shopping basketpublic synchronized void emptyBasket(Agent agent)
while((key=list.getNextKey())!=null)
// Remove the Val object from the shopping cart
list.removeVal(key); repeat=true; break;
Related Topics
setVal( ) and resetPosition( ) in the IValList Interface (deprecated)valIn and valOut in the AppLogic class (deprecated)
execute( ) in the AppLogic class (deprecated)
Resets the iterator position to the "first" GXVAL object in the IValList.
Syntax
public int resetPosition()
Usage
When the contents of an IValList are unknown, the AppLogic can iterate through each GXVAL object and retrieve its key name. Before iterating through the IValList , the AppLogic needs to call resetPosition( ) once to ensure that iteration begins at the "first" GXVAL object in the IValList .
Rule
Do not add or remove GXVAL objects to or from the IValList when iterating through the IValList.The first GXVAL object is not necessarily the first one added to the IValList.
Use resetPosition( ) in conjunction with count( ) and getNextKey( ) to iterate through the IValList.
Return Value
GXE.SUCCESS if the method succeeds.
Example
// Returns the contents of the shopping basketpublic synchronized IValList getBasketContents()
IValList ret = GX.CreateValList();
// Iterate through the contents of the shopping basket
while((key=list.getNextKey())!=null)
// Obtain the product number from the item
String prod = key.substring(PROD.length(),
// Set the return IValList appropriately
ret.setVal(prod, list.getVal(key));
Related Topics
count( ) and getNextKey( ) in the IValList Interface (deprecated)valIn and valOut in the AppLogic class (deprecated)
execute( ) in the AppLogic class (deprecated)
Copies a GXVAL object to the IValList .
Syntax
public int setVal(
String pKey,
GXVAL pVal)pKey. Key name of the GXVAL object to add to the IValList.
pVal. The GXVAL object, identified by pKey, to add to the IValList.
Usage
Use setVal( ) to add an existing GXVAL object to the IValList. If a GXVAL object with the same key name already exists, setVal( ) overwrites it with the new one.
Rule
Do not add new GXVAL objects to the IValList when iterating through the IValList.
Tip
To add a new GXVAL object of type integer, string, or BLOB to the IValList, use setValInt( ), setValString( ), or setValBLOB( ), respectively.
Return Value
GXE.SUCCESS if the method succeeds.
Example
// Returns the contents of the shopping basketpublic synchronized IValList getBasketContents()
IValList ret = GX.CreateValList();
// Iterate through the contents of the shopping basket
while((key=list.getNextKey())!=null)
// Obtain the product number from the item
String prod = key.substring(PROD.length(),
// Set the return IValList appropriately
ret.setVal(prod, list.getVal(key));
Related Topics
valIn and valOut in the AppLogic class (deprecated)execute( ) in the AppLogic class (deprecated)
Adds a BLOB object to the IValList
Syntax
public int setValBLOB(
String pKey,
byte[] pBuff,
int nBuffLen)pKey. Key name of the GXVAL object to add to the IValList.
pBuff. The value of the BLOB object to add to the IValList.
nBuffLen. Number of bytes to set for the byte array. The first nBuffLen bytes in the array pBuff hold the value.
Usage
Use setValBLOB( ) to add a GXVAL object that contains a BLOB value to the IValList. If a GXVAL object with the same key name already exists, setValBLOB( ) overwrites it with the new one.
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
getValBLOB( )
Copies a GXVAL object to the IValList .
Syntax
public int setValByRef(
String pKey,
GXVAL pVal)pKey. Key name of the GXVAL object to add to the IValList.
pVal. The GXVAL object, identified by pKey, to add to the IValList.
Usage
Use setValByRef( ) to add an existing GXVAL object to the IGXValList. If a GXVAL object with the same key name already exists, setValByRef( ) overwrites it with the new one.
Rule
Do not add new GXVAL objects to the IValList when iterating through the IValList.
Tip
To add a new GXVAL object of type integer, string, or BLOB to the IValList, use setValInt( ), setValString( ), or setValBLOB( ), respectively.
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
valIn and valOut in the AppLogic class (deprecated)execute( ) in the AppLogic class (deprecated)
Adds a GXVAL object of type integer to the IValList.
Syntax
public int setValInt(
String pKey,
int nVal)pKey. Key name of the GXVAL object to create or overwrite.
nVal. The integer value to assign to the GXVAL object identified by pKey.
Usage
Use setValInt( ) to add a GXVAL object of type integer to the IValList. If a GXVAL object with the same key name already exists, setValInt( ) overwrites it with the new one.
Rules
When iterating through existing GXVAL objects in the IValList, do not add new GXVAL objects to the IValList.
Tips
To add a new GXVAL object of type string or BLOB to the IValList, use setValString( ) or setValBLOB( ), respectively.
Return Value
GXE.SUCCESS if the method succeeds.
Example
// Specifies the User ID for the Session's IValListpublic void setUserId(int uid, Agent agent)
getValList().setValInt("UserId", uid);
Related Topics
valIn and valOut in the AppLogic class (deprecated)execute( ) in the AppLogic class (deprecated)
Adds a GXVAL object of type string to the IValList.
Syntax
public int SetValString(
String pKey,
String val)pKey. Key name of the GXVAL object to create or overwrite.
val. The string value to assign to the GXVAL object identified by pKey.
Usage
Use setValString( ) to add a GXVAL object of type string to the IValList. If a GXVAL object with the same key name already exists, setValString( ) overwrites it with the new one.
Rules
When iterating through existing GXVAL objects in the IValList, do not add new GXVAL objects to the IValList.
Tips
To add a new GXVAL object of type integer or BLOB to the IValList, use setValInt( ) or setValBLOB( ), respectively.
Return Value
GXE.SUCCESS if the method succeeds.
Example
// Create and IValList and set string valuesIValList custValList = GX.CreateValList();
custValList.setValString(":ssn", ssn);
custValList.setValString(":userName", userName);
Related Topics
valIn and valOut in the AppLogic class (deprecated)execute( ) in the AppLogic class (deprecated)
Previous Contents Index DocHome Next
Copyright © 2001 Sun Microsystems, Inc. Some preexisting portions Copyright © 2001 Netscape Communications Corp. All rights reserved.
Last Updated June 21, 2001