Previous
Contents
Index
Next
|
| iPlanet Application Server 6.5 SP1, Enterprise Edition Java Foundation Class Reference Guide |
| Updated: November 25, 2002 |
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, IOException
response. 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)
IGXAppEvent interface (deprecated)
IAppEventIGXAppEvent is deprecated and is provided for backward compatibility only. New applications should use the iPlanet Application Server API's two replacement interfaces: IAppEventMgrIGXAppEventMgr and IAppEventObjIGXAppEventObj.
The IAppEventIGXAppEvent 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 IAppEventIGXAppEvent interface defines methods for registering, triggering, enabling, disabling and deleting events. To create an instance of the IAppEventIGXAppEvent interface, use the getAppEvent( )GetAppEvent( ) method in the AppLogicGXAppLogic class.
Package Include File
com.kivasoftgxiappevent.h
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( )GetAppEvent( ) method in the AppLogicGXAppLogic class
IAppEventMgr InterfaceIGXAppEventMgr interface
IAppEvent Interface (deprecated)IGXAppEventObj interface
IValList interfaceIGXValList interface
Removes a registered event from the iPlanet Application Server.
Syntax
public int deleteEvent(
String pEventName)
HRESULT DeleteEvent(
LPSTR pEventName);
pEventName. The name of the registered event to delete.
Usage
Use deleteEvent( )DeleteEvent( ) to remove an event that is no longer required. To temporarily stop a event from being triggered, use disableEvent( )DisableEvent( ).
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
disableEvent( )DisableEvent( )
registerEvent( )RegisterEvent( )
Syntax
public int disableEvent(
String pEventName)
HRESULT DisableEvent(
LPSTR pEventName);
pEventName. The name of the registered event to disable.
Usage
Use disableEvent( )DisableEvent( ) to temporarily stop an event from being triggered. The event is disabled until it is enabled with enableEvent( )EnableEvent( ). To remove an event from the iPlanet Application Server permanently, use deleteEvent( )DeleteEvent( ).
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
deleteEvent( )DeleteEvent( )
registerEvent( )RegisterEvent( )
Syntax
public int enableEvent(
String pEventName)
HRESULT EnableEvent(
LPSTR pEventName);
pEventName. The name of the registered event to enable.
Usage
Use enableEvent( )EnableEvent( ) to prepare a specified event for activation. Call enableEvent( )EnableEvent( ) after you register an event with registerEvent( )RegisterEvent( ), or to enable a trigger that was disabled with disableEvent( )DisableEvent( ).
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
disableEvent( )DisableEvent( )
registerEvent( )RegisterEvent( )
Returns the list of registered events.
Syntax
public IEnumObject enumEvent()
HRESULT EnumEvent(
IGXEnumObject **ppEvents);
ppEvent. Pointer to the IGXEnumObject object that contains the list of registered events. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use enumEvents( )EnumEvents( ) to get information on all the registered events. The IEnumObjectIGXEnumObject object returned by enumEvents( )EnumEvents( ) contains a set of IValListIGXValList objects, one per event. Each IValListIGXValList contains the properties assigned to the event when it was registered with registerEvent( )RegisterEvent( ).
Tip
Use the methods in the IEnumObjectIGXEnumObject interface to iterate through the contents of the returned IEnumObjectIGXEnumObject object.
Example
The following AppLogic code shows how to use enumEvents( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
getAppEvent( )GetAppEvent( ) method in the AppLogicGXAppLogic class
IValList interfaceIGXValList interface
Returns the properties of a registered event.
Syntax
public IValList queryEvent(
String pEventName)
HRESULT QueryEvent(
LPSTR pEventName,
IGXValList **ppValList);
pEventName. The name of the registered event to enable.
ppValList. Pointer to the IGXValList object that contains the returned event information. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
When an AppLogic calls registerEvent( )RegisterEvent( ), it can specify any of the following:
- The initial state—enable or disabled—of the event
- The time the event is to be triggered
- The AppLogic to execute when the event is triggered
- The email to send when the event is triggered
Use queryEvent( )QueryEvent( ) to get the properties that were specified for a specific event.
Return Value
IValList object that contains information about the event.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
registerEvent( )RegisterEvent( )
Registers a named event for use in applications.
Syntax
public int registerEvent(
String pEventName,
IValList pValList)
HRESULT RegisterEvent(
LPSTR pEventName,
IGXValList *pValList);
pEventName. The name of the event to register.
pValList. The IValListIGXValList 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( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
The following example shows how to define and register an application event:
Related Topics
enableEvent( )EnableEvent( )
getAppEvent( )GetAppEvent( ) method in the AppLogicGXAppLogic class
IValList interfaceIGXValList interface
Syntax
public int setEvent(
String pEventName,
int dwOverrideFlag,
IValList pValList)
HRESULT SetEvent(
LPSTR pEventName,
DWORD dwOverrideFlag,
IGXValList *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 IValListIGXValList object that specifies the event properties you want to override. Specify nullNULL 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( )SetEvent( ) to trigger a registered event immediately. This is useful for testing purposes.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
registerEvent( )RegisterEvent( )
getAppEvent( )GetAppEvent( ) method in the AppLogicGXAppLogic class
IValList interfaceIGXValList interface
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 IAppEventMgrIGXAppEventMgr interface manages application events. This interface defines methods for creating, registering, triggering, enabling, disabling, enumerating, and deleting events.
- The IAppEventObjIGXAppEventObj 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.
IAppEventMgrIGXAppEventMgr and IAppEventObjIGXAppEventObj should be used in new or migratedrevised applications. Existing iPlanet Application Server applications can continue using the deprecated IAppEventIGXAppEvent interface, which supports the previous model for application events.
Attributes and Actions
For each event, you define associated attributes and actions. Attributes determine the following characteristics:
- the event's state (enabled or disabled)
- the execution mode (concurrent or serial) of the event's actions
- the time at which to trigger the event
When an event is triggered, it performs one or more of the following types of actions:
Features of Application Event Support
Support for application events includes the following:
- Added functionality
- Execution of multiple actions of any type. (IAppEventIGXAppEvent supports only one action of each type.)
- In 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. (IAppEventIGXAppEvent 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 IValListIGXValList object to triggered events.
- Different interfaces
Previously, application events were represented by an IValListIGXValList object, and you used the IAppEventIGXAppEvent interface to manage the events. Now an application event is represented by an IAppEventObjIGXAppEventObj, and you use IAppEventMgrIGXAppEventMgr to manage and control the events.
- Separate actions and attributes
Previously, attributes and actions were not distinguished. They were all treated as event properties and specified within a single IValListIGXValList object. Now attributes are described by entries in one IValListIGXValList object, and each action is represented by its own additional IValListIGXValList object.
IAppEventObjIGXAppEventObj 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.
To access an IGXAppEventMgr object, use the C++ helper function GXContextGetAppEventMgr( ):
HRESULT GXContextGetAppEventMgr(
IGXContext *pContext
IGXAppEventMgr **ppAppEventMgr);
The pContext parameter is a pointer to an IGXContext object, which provides access to Netscape Application Server services. Specify a value of m_pContext, a member variable in the GXAppLogic class.
The ppAppEventMgr parameter is a pointer to the returned IGXAppEventMgr object.
After creating the IAppEventMgrIGXAppEventMgr object, you can create an application event (an instance of IAppEventObjIGXAppEventObj) by calling createEvent( )CreateEvent( ) on the IAppEventMgrIGXAppEventMgr object.
Registering Events
After creating an application event, you can set its attributes and add actions using methods on the IAppEventObjIGXAppEventObj. Then, register the application event by calling registerEvent( )registerEvent( ) on the manager object.
Package Include File
com.kivasoftgxiappevent.h
Method
Description
Retrieves the IAppEventObjIGXAppEventObj for a registered event.
Related Topics
GetAppEventMgr( ) in the GXContext classGXContextGetAppEventMgr( ),
IValList Interface (deprecated)IGXAppEventMgr interface,
IAppEvent Interface (deprecated)IGXAppEventObj interface
Creates an empty application event object.
Syntax
public IAppEventObj createEvent(
String pEventName)
HRESULT CreateEvent(
LPSTR pEventName
IGXAppEventObj **appeventObj);
pEventName. The name of the event to create.
appeventObj. A pointer to the returned IGXAppEventObj.
Usage
Use createEvent( )CreateEvent( ) to create an empty IAppEventObjIGXAppEventObj object. You can use methods of the IAppEventObjIGXAppEventObj 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( )RegisterEvent( ).
Call the Release( ) method (defined in the IGXObject interface) when you are done.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
queryEvent( )GetEvent( )
registerEvent( )RegisterEvent( )
Removes a registered event from iPlanet Application Server.
Syntax
public int deleteEvent(
String pEventName)
HRESULT DeleteEvent(
LPSTR pEventName);
pEventName. The name of the registered event to delete.
Usage
Use deleteEvent( )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( )DisableEvent( ).
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
disableEvent( )DisableEvent( )
registerEvent( )RegisterEvent( )
Syntax
public int disableEvent(
String pEventName)
HRESULT DisableEvent(
LPSTR pEventName);
pEventName. The name of the registered event to disable.
Usage
Use disableEvent( )DisableEvent( ) to temporarily stop an event from being triggered. The event is disabled until it is enabled with enableEvent( )EnableEvent( ). To permanently remove an event from the registry, use deleteEvent( )DeleteEvent( ).
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
deleteEvent( )DeleteEvent( )
registerEvent( )RegisterEvent( )
Syntax
public int enableEvent(
String pEventName)
HRESULT EnableEvent(
LPSTR pEventName);
pEventName. The name of the registered event to enable.
Usage
Use enableEvent( )EnableEvent( ) to enable an event. A given event could have been disabled in either of two ways: by a previous call to disableEvent( )DisableEvent( ) or by initially registering the event using a disabled state attribute.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
disableEvent( )DisableEvent( )
registerEvent( )RegisterEvent( )
Enumerates through the list of registered events.
Syntax
public IEnumObject enumEvents()
HRESULT EnumEvents(
IGXEnumObject **ppEvents);
ppEvents. Pointer to the IGXEnumObject object that contains the list of registered events. When an application component is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use enumEvents( )EnumEvents( ) to get information on all the registered events. The IEnumObjectIGXEnumObject object returned by enumEvents( )EnumEvents( ) contains a set of IAppEventObjIGXAppEventObj objects, one per event. Each IAppEventObjIGXAppEventObj contains the attributes and actions that were assigned to the event when it was registered with registerEvent( )RegisterEvent( ).
Tip
Use the methods in the IEnumObjectIGXEnumObject interface to iterate through the contents of the returned IEnumObjectIGXEnumObject object.
Example
The following AppLogic code shows how to use enumEvents( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
IEnumObjectIGXEnumObject interface
Retrieves the IAppEventObjIGXAppEventObj for a registered event.
Syntax
public IAppEventObj getEvent(
String pEventName)
HRESULT GetEvent(
LPSTR pEventName,
IGXAppEventObj **ppAppEvent);
pEventName. The name of the registered event.
ppAppEvent. Pointer to the IGXAppEventObj object for the given event. When the application component is finished using the object, call the Release( ) method to release the interface instance.
Usage
After calling getEvent( )GetEvent( ), you can call methods on the returned IAppEventObjIGXAppEventObj. For example, you can query the object by calling getAttributes( )GetAttributes( ) or enumActions( )EnumActions( ), or you can modify the object by calling setAttributes( )SetAttributes( ).
Return Value
IAppEventObj for the specified event.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
registerEvent( )RegisterEvent( )
Registers a named event for use in applications.
Syntax
public int registerEvent(
IAppEventObj appEventObj)
HRESULT RegisterEvent(
IGXAppEventObj *appEventObj);
appEventObj. The event object whose attributes and actions have been set.
Usage
After an application event object is created with createEvent( )CreateEvent( ), you define its attributes and actions using methods of the IAppEventObjIGXAppEventObj interface. Then you use registerEvent( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
The following example shows how to define and register an application event:
Related Topics
enableEvent( )EnableEvent( )
Syntax
public int triggerEvent(
String pEventName,
IValList pValList,
boolean syncFlag)
HRESULT TriggerEvent(
LPSTR pEventName,
IGXValList *pValList,
BOOL syncFlag);
pEventName. The name of the event to trigger.
pValList. The IValListIGXValList 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( )TriggerEvent( ) to trigger a registered event. When you specify the pValList parameter, a copy of this IValListIGXValList 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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
registerEvent( )RegisterEvent( )
See the IAppEventMgrIGXAppEventMgr interface for details on IAppEventObjIGXAppEventObj.
Package Include File
com.kivasoftgxiappevent.h
Related Topics
IAppEventMgrIGXAppEventMgr interface
Appends an action to an ordered list of actions.
Syntax
public int addAction(
IValList action)
HRESULT AddAction(
IGXValList *action);
action. The input IValListIGXValList 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 IValListIGXValList 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( )AddAction( ) method after creating an application event object (by calling createEvent( )CreateEvent( ) on the IAppEventMgrIGXAppEventMgr 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( )EnumActions( ). To delete all actions, use deleteActions( )DeleteActions( ).
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Deletes all actions added to this IGXAppEventObj.
Syntax
public int deleteActions()
Usage
Use this method to remove all actions associated with this IGXAppEventObj.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Enumerates the actions added to this IGXAppEventObj.
Syntax
public IEnumObject enumActions()
HRESULT EnumActions(
IGXEnumObject **actions);
actions. A pointer to the returned IGXEnumObject.
Usage
Use this method to obtain a list of actions that have been added to this IGXAppEventObj. Each entry in the returned IGXEnumObject is an IGXValList object representing an action.
Return Value
IEnumObject that contains the list of actions, or null for failure.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Retrieves the list of attributes of an IGXAppEventObj.
Syntax
public IValList getAttributes()
HRESULT GetAttributes(
IGXValList **attrList);
attrList. A pointer to the returned IGXValList object.
Usage
Call this method after calling setAttributes( )SetAttributes( ).
Return Value
IValList object that contains the list of attributes, or null for failure.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
setAttributes( )SetAttributes( )
Retrieves the name of the IGXAppEventObj.
Syntax
public String getName()
HRESULT GetName(
LPSTR pName,
unsigned long nName);
pName. A pointer to an input buffer.
nName. The size of the input buffer.
Usage
The name of an IGXAppEventObj is set by calling createEvent( )CreateEvent( ) on the IGXAppEventMgr object. After creating an application event object, use the getName( )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 IGXAppEventObj.
Syntax
public int setAttributes(
IValList attrList)
HRESULT SetAttributes(
IGXValList *attrList);
attrList. The input IGXValList 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
A variableAn enum that specifies the initial state of the event. This key is optional and has the following possible values:
- GXConstants.GX_AE2_RE_KEY_TIME
An optional key that specifies the time at which the event will be triggered. Use the following format:
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 *.
- GXConstants.GX_AE2_RE_KEY_ACTION_MODE
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( )SetAttributes( ) method after creating an application event object (by calling createEvent( )CreateEvent( ) on the IAppEventMgrIGXAppEventMgr 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( )GetAttributes( ).
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
getAttributes( )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 IBufferIGXBuffer interface represents a block of memory. Input arguments and output value(s) of methods are sometimes stored in IBufferIGXBuffer objects. For example, the get**( )Get**( ) methods in the IQueryIGXQuery interface return values in an IBufferIGXBuffer object.
IBuffer IGXBuffer 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 IGXBuffer interface, use the GX.CreateBuffer( ) methodGXCreateBuffer( ) function. To create and initialize an IBuffer object with string contents, use GX.CreateBufferFromString( ).
Package Include File
com.kivasoft gxibuff.h
Method
Description
Returns a copy of the buffer contents.Returns the address of the memory block.
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( )GXCreateBuffer( ) function, use alloc( )Alloc( ) to specify its size.
Subsequent calls to getSize( )GetSize( ) return the size that AppLogic specified when it called alloc( )Alloc( ).
- If the AppLogic creates its own new IBuffer IGXBuffer object, it must first specify the size of the memory block by calling alloc( )Alloc( ) before using other methods in the interface.
- AppLogic can call alloc( )Alloc( ) only once.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
LPSTR str = "Hello World"; IGXBuffer buff; buff = GXCreateBuffer(); buff->Alloc(128); buff->SetData((LPBYTE) str, 12);
Related Topics
getAddress( )GetAddress( )
Returns a copy of the buffer contents.
Returns the address of the memory block.
Syntax
public byte[] getAddress()
Usage
Use getAddress( ) to get a copy of the contents in a buffer.
Use GetAddress( ) to obtain the starting address of the buffer that was allocated by Alloc( ). The starting address of the buffer is needed when copying data to and from the buffer.
Rule
Before calling GetAddress( ), the memory buffer must be allocated first by calling Alloc( ). When the system returns an IGXBuffer object (for example, when the AppLogic calls a Get**( ) method in the IGXQuery interface), it automatically allocates the memory buffer.
Return Value
A copy of the buffer contents.
// Use IGXBuffer interface here. The memory held by
// the IGXBuffer object should be treated as read-only.
StreamResult("The tables accessed by the query are ");
StreamResult((LPSTR) buff->GetAddress());
// Release buff when done with it.
Related Topics
alloc( )Alloc( )
Returns the size of the memory block, in bytes.
Usage
Use getSize( )GetSize( ) to determine the length of the memory buffer that the AppLogic specified when it called alloc( )Alloc( ).
Rule
Before calling getSize( )GetSize( ), AppLogic must first specify the size of the memory block by calling alloc( )Alloc( ).
Return Value
GXE.SUCCESS if the method succeeds.
Size of the memory block, in bytes.
Related Topics
getAddress( )GetAddress( )
Copies data to a memory block.
Syntax
public int setData(
byte[] pData,
int nDataLen)
HRESULT SetData(
LPBYTE pData,
ULONG 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( )SetData( ) to copy data to a memory buffer. The buffer can then be passed to a method, such as the setValPieceByOrd( )SetValPieceByOrd( ) method in the ITableIGXTable interface, that accepts data values in a buffer object.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
LPSTR str = "Hello World"; IGXBuffer buff; buff = GXCreateBuffer(); buff->Alloc(128); buff->SetData((LPBYTE) str, 12); table->SetValPieceByOrd(1, buff, 12); buff->Release();
Related Topics
getAddress( )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 IGXCallableStmt 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 ICallableStmtIGXCallableStmt object. The ICallableStmt IGXCallableStmt 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 IGXCallableStmt interface, use prepareCall( )PrepareCall( ) in the IDataConn IGXDataConn interface.
Package Include File
com.kivasoft gxidata.h
Related Topics
prepareCall( )PrepareCall( ) in the IDataConn Interface (deprecated)IGXDataConn interface
Releases the callable statement.
Usage
Use close( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Executes the stored procedure called by the ICallableStmtIGXCallableStmt object.
Syntax
public IResultSet execute(
int flags,
IValList params,
ITrans trans,
IValList props);
HRESULT Execute(
DWORD dwFlags,
IGXValList *pParams,
IGXTrans *pTrans,
IGXValList *pProps,
IGXResultSet **ppResultSet);
- 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 pParams. IValList Pointer to an IGXValList object that contains parameters to pass to the callable statement. If you use setParams( )SetParams( ) instead to specify the parameters, specify nullNULL here.
trans pTrans. ITrans Pointer to an IGXTrans object that contains the transaction associated with this callable statement, or nullNULL for no transaction.
props pProps. IValListPointer to the IGXValList object that contains properties, or nullNULL 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 interfaceIGXValList interface, set any of the following properties:
- RS_BUFFERING turns on result set buffering when set to "TRUE" or "YES."
- RS_INIT_ROWS specifies the initial size of the buffer, in number of rows. If the result set size exceeds this setting, a fetchNext( )FetchNext( ) call will return the error GX_DA_FETCHNEXT_RESULTS.GX_DA_BUFFER_EXCEEDEDGX_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( )FetchNext( ) call will return the error GX_DA_FETCHNEXT_RESULTS.GX_DA_BUFFER_EXCEEDEDGX_DA_BUFFER_EXCEEDED and result set buffering will be turned off.
- RS_MAX_SIZE specifies the maximum number of bytes for the buffer.
If RS_BUFFERING is enabled and if the optional parameters are not specified, the global values in the registry are used instead.
ppResultSet. Pointer to the IGXResultSet object that contains the returned result set from the stored procedure, if the database supports this feature. Informix, DB2, MS SQL Server and Sybase support it. When the AppLogic is finished using the object, call the Close( ) method in the IGXResultSet interface, then call the Release( ) method to release the interface instance.
Usage
Use execute( )Execute( ) to run a callable statement that has been created with prepareCall( )PrepareCall( ) in the IDataConnIGXDataConn interface. If the stored procedure called by the ICallableStmtIGXCallableStmt object can return multiple result sets, use executeMultipleRS( )ExecuteMultipleRS( ) instead.
If the stored procedure called by the ICallableStmtIGXCallableStmt object contains parameters, instantiate an IValListIGXValList object and use setValString( )SetVal( ) or setValInt( )SetValByRef( ) in the IValList interfaceIGXValList interface to specify the parameter values to pass to the stored procedure.
After creating and setting up the IValListIGXValList object, pass it to execute( )Execute( ) or setParamsSetParams( ). If you use setParams( )SetParams( ) to pass parameters to the stored procedure, specify NULL for the params parameter in execute( )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).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
prepareCall( )PrepareCall( ) in the IDataConn Interface (deprecated)IGXDataConn interface
Executes a stored procedure, called by the ICallableStmtIGXCallableStmt object, that can return multiple result sets.
Syntax
public int executeMultipleRS(
int dwFlags,
IValList pParams,
ITrans pTrans,
IValList pProps);
HRESULT ExecuteMultipleRS(
DWORD dwFlags,
IGXValList *pParams,
IGXTrans *pTrans,
IGXValList *pProps)
pParams. IValList Pointer to an IGXValList object that contains parameters to pass to the callable statement. If no parameters are required, pass in an empty IValListIGXValList. If you use setParams( )SetParams( ) instead to specify the parameters, specify nullNULL here.
pTrans. ITrans Pointer to an IGXTrans object that contains the transaction associated with this callable statement, or nullNULL for no transaction.
pProps. IValListPointer to the IGXValList object that contains properties, or nullNULL for no properties.
After instantiating an object of the IValList interfaceIGXValList interface, set any of the following properties:
- RS_BUFFERING turns on result set buffering when set to "TRUE" or "YES."
- RS_INIT_ROWS specifies the initial size of the buffer, in number of rows. If the result set size exceeds this setting, a fetchNext( )FetchNext( ) call will return the error GX_DA_FETCHNEXT_RESULTS.GX_DA_BUFFER_EXCEEDEDGX_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( )FetchNext( ) call will return the error GX_DA_FETCHNEXT_RESULTS.GX_DA_BUFFER_EXCEEDEDGX_DA_BUFFER_EXCEEDED and result set buffering will be turned off.
- RS_MAX_SIZE specifies the maximum number of bytes for the buffer.
If RS_BUFFERING is enabled and if the optional parameters are not specified, the global values in the registry are used instead.
Usage
Use executeMultipleRS( )ExecuteMultipleRS( ) to run a callable statement that returns multiple result sets. The callable statement should already have been created with prepareCall( )PrepareCall( ) in the IDataConnIGXDataConn interface.
If the stored procedure called by the ICallableStmtIGXCallableStmt object contains parameters, instantiate an IValListIGXValList object and use setValString( )SetVal( ) or setValInt( )SetValByRef( ) in the IValList interfaceIGXValList interface to specify the parameter values to pass to the stored procedure.
After creating and setting up the IValListIGXValList object, pass it to executeMultipleRS( )ExecuteMultipleRS( ) or setParamsSetParams( ). If you use setParams( )SetParams( ) to pass parameters to the stored procedure, specify NULL for the pParams parameter in executeMultipleRS( )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( )Execute( ) and executeMultipleRS( )ExecuteMultipleRS( ) is that execute( )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( )ExecuteMultipleRS( ).
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
prepareCall( )PrepareCall( ) in the IDataConn Interface (deprecated)IGXDataConn interface
getMoreResults( )GetMoreResults( )
getResultSet( )GetResultSet( )
Checks if there is a result set to retrieve. This method is valid only if you used executeMultipleRS( )ExecuteMultipleRS( ) (instead of execute( )Execute( )) to execute a stored procedure called by the ICallableStmtIGXCallableStmt object.
Syntax
public boolean getMoreResults()
HRESULT GetMoreResults(
BOOL *pMoreResult)
pMoreResult. Pointer to the client-allocated BOOL variable that contains the returned information.
Usage
If you used executeMultipleRS( )ExecuteMultipleRS( ) to execute a stored procedure that returns multiple results sets, use getMoreResults( )GetMoreResults( ) in conjunction with getResultSet( )GetResultSet( ) to check if there is a result set before retrieving it.
If there is a current result set with unretrieved rows, getMoreResults( )GetMoreResults( ) discards the current result set and makes the next result set available.
Return Value
True if there is a result set.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
prepareCall( )PrepareCall( ) in the IDataConn Interface (deprecated)IGXDataConn interface
executeMultipleRS( )ExecuteMultipleRS( )
getResultSet( )GetResultSet( )
Returns the value of the stored procedure's output parameter or parameters.
Syntax
public IValList getParams(
int dwFlags);
HRESULT GetParams(
DWORD dwFlags
IGXValList **ppParams);
ppParams. Pointer to the IGXValList object that contains the stored procedure's output parameters. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Some stored procedures return output parameters. If the stored procedure your callable statement executes returns output parameters, use getParams( )GetParams( ) to get the values.
The getParams( )GetParams( ) method returns the values in an IValListIGXValList object. The key names associated with the values are the parameter names as specified in the query that was passed to the prepareCall( )PrepareCall( ) method.
Tip
Informix stored procedures return output parameters in a result set. This result set is returned by execute( )Execute( ) or executeMultipleRS( )ExecuteMultipleRS( ). The getParams( )GetParams( ) method, therefore, does not apply to Informix stored procedures.
Return Value
IValList object, or null for failure.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
prepareCall( )PrepareCall( ) in the IDataConn Interface (deprecated)IGXDataConn interface
Retrieves a result set. This method is valid only if you used executeMultipleRS( )ExecuteMultipleRS( ) (instead of execute( )Execute( )) to execute a stored procedure called by the ICallableStmtIGXCallableStmt object.
Syntax
public IResultSet getResultSet()
HRESULT GetResultSet(
IGXResultSet **ppResultSet)
ppResultSet. Pointer to the IGXResultSet object that contains the returned result set. When the AppLogic is fnished using the object, call the Release( ) method to release the interface instance.
Usage
If you used executeMultipleRS( )ExecuteMultipleRS( ) to execute a stored procedure that returns multiple results sets, use getResultSet( )GetResultSet( ) in conjunction with getMoreResults( )GetMoreResults( ) to retrieve the results sets.
Return Value
IResultSet object, or null if there is no result set.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
prepareCall( )PrepareCall( ) in the IDataConn Interface (deprecated)IGXDataConn interface
executeMultipleRS( )ExecuteMultipleRS( )
getMoreResults( )GetMoreResults( )
Specifies the parameter values to pass to the stored procedure.
Syntax
public int setParams(
int dwFlags,
IValList pParams);
HRESULT SetParams(
DWORD dwFlags
IGXValList *pParams);
dwFlags. Specify 0 (zero). For internal use only.
pParams. Pointer to the IGXValListIValList 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( )Execute( ) is called. If you use setParams( )SetParams( ), specify NULL for the pParams parameter in execute( )Execute( ).
Usage
If the stored procedure the callable statement executes accepts input parameters, use setParams( )SetParams( ) to pass the parameter or parameter values. The alternative is to pass the parameter values with the execute( )Execute( ) method. Parameters passed to execute( )Execute( ) supersede parameters specified with setParams( )SetParams( ).
For both setParams( )SetParams( ) and execute( )Execute( ), you pass the parameter values in an IGXValListIValList object.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
prepareCall( )PrepareCall( ) in the IDataConn Interface (deprecated)IGXDataConn interface
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 Interface
javax.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 IGXColumn interface represents a column definition in a table. IColumn IGXColumn 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 IGXColumn is part of the Data Access Engine (DAE) service.
To create an instance of this interface, use one of the following methods:
- getColumn( )GetColumn( ) or getColumnByOrd( )GetColumnByOrd( ) in the IHierResultSet Interface (deprecated)IGXHierResultSet interface
- getColumn( )GetColumn( ), getColumnByOrd( )GetColumnByOrd( ), or enumColumns( )EnumColumns( ) in the ITable Interface (deprecated)IGXTable interface
- getColumn( )GetColumn( ), getColumnByOrd( )GetColumnByOrd( ), or enumColumns( )EnumColumns( ) in the IResultSet Interface (deprecated)IGXResultSet interface
The following example shows creating an IColumn object:
ITable tbl = conn.getTable("Products");
IColumn col = tbl.getColumnByOrd(1);
Package Include File
com.kivasoft gxidata.h
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( )GetColumn( ) or getColumnByOrd( )GetColumnByOrd( ) in the IHierResultSet Interface (deprecated)IGXHierResultSet interface
getColumn( )GetColumn( ), getColumnByOrd( )GetColumnByOrd( ), or enumColumns( )EnumColumns( ) in the ITable Interface (deprecated)IGXTable interface
getColumn( )GetColumn( ), getColumnByOrd( )GetColumnByOrd( ), or enumColumns( )EnumColumns( ) in the IResultSet Interface (deprecated)IGXResultSet interface
Returns the name of the column or alias.
Syntax
public String getName()
HRESULT GetName(
LPSTR pBuff,
ULONG nBuff);
pBuff. Buffer allocated by the client to hold the zero-terminated string that contains the returned column name or alias.
nBuff. Length of the buffer allocated by the client for the returned column name or alias.
Usage
Use getName( )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( )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).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
The following example shows how to iterate through a table to get the names of columns:
Related Topics
"Getting Information About Columns or Fields"
Determines whether nullNULL values are allowed in the column.
Syntax
public boolean getNullsAllowed()
HRESULT GetNullsAllowed(
BOOL *pNullsAllowed);
pNullsAllowed. Pointer to the variable that contains the returned boolean result.
Usage
A column may require data values. Use getNullsAllowed( )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).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
The following example shows how to iterate through a tableresult set and return the column names, as well as whether null values are allowed in each column:
Related Topics
"Getting Information About Columns or Fields"
Returns the precision, which is the maximum length or maximum number of digits, of the column.
Syntax
public int getPrecision()
HRESULT GetPrecision(
ULONG *pPrecision);
pPrecision. Pointer to the variable that contains the returned precision, which represents the maximum length or maximum number of digits of the column.
Usage
Use getPrecision( )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).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
The following example shows how to iterate through a tableresult set and return the column names, as well as the precision value of each column:
Related Topics
"Getting Information About Columns or Fields"
Returns the scale, which is the number of digits to the right of the decimal point, of a column of type double.
HRESULT GetScale(
ULONG *pScale);
pScale. Pointer to the variable that contains the returned scale, which represents the fixed number of digits to the right of the decimal point.
Usage
Use getScale( )GetScale( ) when the scale of the column is unknown and is required for subsequent operations.
- Use getScale( )GetScale( ) with numeric columns, including SQL DECIMAL, NUMERIC, and FLOAT data types.
- The value returned from getScale( )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( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
"Getting Information About Columns or Fields"
Returns the maximum length, in number of bytes, allowed for a value in this column.
HRESULT GetSize(
ULONG *pSize);
pSize. Pointer to the variable that contains the returned size, which represents the maximum length of the column.
Usage
Use getSize( )GetSize( ) when the maximum allowable length of the column is unknown and is required for subsequent operations. Note that getSize( )GetSize( ) does not return the actual size of data in the column.
- The value returned from getSize( )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( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
The following example shows how to iterate through a tableresult set and return the column names, as well as the maximum allowable length of each column:
Related Topics
"Getting Information About Columns or Fields"
Returns the table object in which this column exists.
Syntax
public ITable getTable()
HRESULT GetTable(
IGXTable **ppTable);
ppTable. Pointer to the returned IGXTable object that contains the table definition associated with this column. When AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use getTable( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
ITable Interface (deprecated)IGXTable interface
"Getting Information About Columns or Fields"
Returns the data type of the column.
HRESULT GetType(
DWORD *pdwType);
pdwType. Pointer to the variable that contains one of the following macro-defined constants (defined in gxidata.h), which represent SQL data types.
Note: Some SQL data types are combined under a single category of data types. For example, GX_DA_TYPE_LONG includes short and integer data types, as well as tiny, small, and big integers.
Variable
Description
All binary data types, including binary large objects (BLOBs).
Timestamp (date and time) data type. See the GXDATETIME struct
Double and related data types, including real, float, and decimal data types.
String and related data types, including char and variable-length strings.
Use getType( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
"Getting Information About Columns or Fields"
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 IGXDataConn interface represents a connection to a relational data source. IDataConn IGXDataConn 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 IGXDataConn is part of the Data Access Engine (DAE) service. To create an instance of the IDataConn IGXDataConn interface, use createDataConn( )CreateDataConn( ) in the AppLogic class (deprecated)GXAppLogic class, as shown in the following example:.
if((conn = createDataConn(0, GX_DA_DAD_DRIVERS.GX_DA_DRIVER_ODBC, "CATALOG", "CATALOG", "steve", "pass7878")) == null)
Package Include File
com.kivasoft gxidata.h
Method
Description Creates a new trigger object in the specified table.
Disables a trigger associated with a specified table. This feature is supported by Oracle databases only. Removes a trigger from a specified table.
Enables a trigger for a specified table. This feature is supported by Oracle databases only.
Returns database and user information about the current database connection.
Returns registry information about the current database connection.
getDriver( )GetDriver( )
Returns the identifier of the data source driver that the current database connection is using.
Returns the table definition object for the specified table.
Returns an IValListIGXValList of database tables or views that are available to the specified user.
Creates an ICallableStmtIGXCallableStmt object that contains a call to a stored procedure.
Specifies registry values for the current database connection.
Related Topics
createDataConn( )CreateDataConn( ) in the AppLogic class (deprecated)AppLogic class (deprecated)
getDataConn( )GetDataConn( ) in the ITable Interface (deprecated)IGXTable interface
addRow( )AddRow( ), deleteRow( )DeleteRow( ), and updateRow( )UpdateRow( ) in the ITable Interface (deprecated)IGXTable interface
"Running Hierarchical Queries"
"Inserting Records in a Database," "Updating Records in a Database," and "Deleting Records From a Database"
Explicitly closes the database connection.
Syntax
public int closeConn(
int dwFlags)
HRESULT CloseConn(
DWORD 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( )CloseConn( ) to explicitly close a database connection and release system resources, such as when memory is low. Calling closeConn( )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 IGXDataConn 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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
createDataConn( )CreateDataConn( ) in the AppLogic class (deprecated)GXAppLogic class
Creates a new trigger object in the specified table.
Syntax
int createTrigger(
String pTable,
String pName,
String pCondition,
String pOptions,
String pSQLBlock);
HRESULT CreateTrigger(
LPSTR pTable,
LPSTR pName,
LPSTR pCondition,
LPSTR pOptions,
LPSTR 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( )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( )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( )EnableTrigger( ), but it will have no effect.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
disableTrigger( )DisableTrigger( )
enableTrigger( )EnableTrigger( )
Disables a trigger associated with a specified table. This feature is supported by Oracle databases only.
Syntax
public int disableTrigger(
String pTable,
String pName);
HRESULT DisableTrigger(
LPSTR pTable,
LPSTR pName);
pTable. The table in which the trigger is located.
pName. The name of the trigger to disable.
Usage
Use disableTrigger( )DisableTrigger( ) to temporarily stop a trigger from being activated. The trigger is disabled until it is enabled with enableTrigger( )EnableTrigger( ). To remove a trigger from a table permanently, use dropTrigger( )DropTrigger( ).
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
createTrigger( )CreateTrigger( )
enableTrigger( )EnableTrigger( )
Removes a trigger from a specified table.
Syntax
public int dropTrigger(
String pTable,
String pName);
HRESULT DropTrigger(
LPSTR pTable,
LPSTR pName);
pTable. The table on which the trigger is defined.
pName. The name of the trigger to remove.
Usage
Use dropTrigger( )DropTrigger( ) to delete a trigger that is no longer required. To temporarily stop a trigger from being activated, use disableTrigger( )DisableTrigger( ).
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
createTrigger( )CreateTrigger( )
disableTrigger( )DisableTrigger( )
enableTrigger( )EnableTrigger( )
Enables a trigger for a specified table. This feature is supported by Oracle databases only.
Syntax
public int enableTrigger(
String pTable,
String pName);
HRESULT EnableTrigger(
LPSTR pTable,
LPSTR pName);
pTable. The table on which the trigger is defined.
pName. The name of the trigger to enable.
Usage
Use enableTrigger( )EnableTrigger( ) to prepare a specified trigger for activation. Call enableTrigger( )EnableTrigger( ) after you create a trigger with createTrigger( )CreateTrigger( ), or to enable a trigger that was disabled with disableTrigger( )DisableTrigger( ).
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
createTrigger( )CreateTrigger( ); disableTrigger( )DisableTrigger( )
Executes a flat query on the data connection.
Syntax
public IResultSet executeQuery(
int dwFlags,
IQuery pQuery,
ITrans pTrans,
IValList pProps)
HRESULT ExecuteQuery(
DWORD dwFlags,
IGXQuery *pQuery,
IGXTrans *pTrans,
IGXValList *pProps,
IGXResultSet **ppResultSet);
dwFlags. Specifies flags used to execute this query.
- For synchronous operations, the default, specify zero or GX_DA_EXECUTEQUERY_FLAGS.GX_DA_EXEC_SYNC.
- For asynchronous operations, specify GX_DA_EXECUTEQUERY_FLAGS.GX_DA_EXEC_ASYNC.
- To activate result set buffering, specify GX_DA_EXECUTEQUERY_FLAGS.GX_DA_RS_BUFFERING.
The AppLogic can pass both result set buffering and either synchronous or asynchronous queries as the flags parameter, as shown in the following example:
(GX_DA_EXECUTEQUERY_FLAGS.GX_DA_EXEC_ASYNC | GX_DA_EXECUTEQUERY_FLAGS.GX_DA_RS_BUFFERING)
pQuery. IQuery Pointer to the IGXQuery object that contains the flat query object to execute.
pTrans. ITrans Pointer to the IGXTrans object that contains the transaction to which this query applies, or nullNULL.
pProps. IValListPointer to the IGXValList object that contains query properties, or nullNULL for no properties. After instantiating an object of the IValList interfaceIGXValList interface, set any of the following properties:
- RS_BUFFERING turns on result set buffering when set to "TRUE".
- RS_INIT_ROWS specifies the initial size of the buffer, in number of rows. If the result set size exceeds this setting, a fetchNext( )FetchNext( ) call will return the error GX_DA_FETCHNEXT_RESULTS.GX_DA_BUFFER_EXCEEDEDGX_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( )FetchNext( ) call will return the error GX_DA_FETCHNEXT_RESULTS.GX_DA_BUFFER_EXCEEDEDGX_DA_BUFFER_EXCEEDED.
- RS_MAX_SIZE specifies the maximum number of bytes for the buffer.
If RS_BUFFERING is enabled and if the optional parameters are not specified, the global values in the registry are used instead.
ppResultSet. Pointer to the IGXResultSet object that contains the returned result of the query. When the AppLogic is finished using the object, and after calling the CloseConn( ) method, call the Release( ) method to release the interface instance.
- Before calling executeQuery( )ExecuteQuery( ), AppLogic must create a query by first calling createQuery( )createQuery( ) in the AppLogic class (deprecated)GXAppLogic class to create the IQueryIGXQuery object, then using methods in the IQuery Interface (deprecated)IGXQuery interface to define the query.
- If the query is part of a transaction, before calling executeQuery( )ExecuteQuery( ), the AppLogic must first create the ITransIGXTrans transaction object using createTrans( )CreateTrans( ) in the AppLogic class (deprecated)GXAppLogic class, then begin the transaction using begin( )Begin( ) in the ITrans Interface (deprecated)IGXTrans interface, and then specify the ITransIGXTrans object as a parameter when calling executeQuery( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
createDataConn( )CreateDataConn( ) in the AppLogic class (deprecated)GXAppLogic class
IQuery Interface (deprecated)IGXQuery interface
IResultSet Interface (deprecated)IGXResultSet interface
ITrans Interface (deprecated)IGXTrans interface
IValList interfaceIGXValList interface
Returns database and user information about the current database connection.
Syntax
public IValList getConnInfo()
HRESULT GetConnInfo(
IGXValList **ppConnInfo);
ppConnInfo. A pointer to the IGXValList object that contains the returned connection information. When the client code is finished using the object, call the Release( ) method to release the interface instance.
Usage
When the client code calls the createDataConn( )CreateDataConn( ) method in the AppLogicGXAppLogic 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( )GetConnInfo( ) to return the datasource, database, user, and password values.
Tip
To return the driver value, use getDriver( )GetDriver( ).
Return Value
IValList object, or null for failure.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Returns registry information about the current database connection.
Syntax
public IValList getConnProps()
HRESULT GetConnProps(
IGXValList **ppProps);
ppProps. A pointer to the IGXValList object that contains the returned connection information. When the client code is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use getConnProps( )GetConnProps( ) to get database connection information that the iPlanet Application Server administrator set through the Enterprise Administrator. The information is returned in an IValListIGXValList object that contains the following keys and values:
The getConnProps( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
setConnProps( )SetConnProps( )
Returns the identifier of the data source driver that the current database connection is using.
HRESULT GetDriver(
DWORD *pdwDriver);
pdwDriver. Pointer to the variable that contains the returned driver information, which can be one of the following:
Usage
When the client code calls the createDataConn( )CreateDataConn( ) method in the AppLogicGXAppLogic 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 IDataConnIGXDataConn interface to return the values that were passed to createDataConn( )CreateDataConn( ).
Call getDriver( )GetDriver( ) to return the driver information.
Tip
To return the datasource, database, user, and password values, use getConnInfo( )GetConnInfo( ).
Return Value
An int value corresponding to one of the static variables in the GX_DA_DAD_DRIVERS class.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Returns the table definition object for the specified table.
Syntax
public ITable getTable(
String szTable)
HRESULT GetTable(
LPSTR szTable,
IGXTable **ppTable);
szTable. Name of the table to request. This can include the schema name, for example, "jim.myTable." Do not use patterns or wildcards.
ppTable. Pointer to the IGXTable object that contains the returned result of the query. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use getTable( )GetTable( ) for the following reasons:
- To change data in the table using methods in the ITable Interface (deprecated)IGXTable interface 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( )GetTable( ) only once to obtain a table definition. Subsequent calls return a separate ITableIGXTable object that represents the same table. Each AppLogic can call getTable( )GetTable( ) and operate on its own copy of the table definition.
- If the table name is unknown, use getTables( )GetTables( ) to retrieve an IValListIGXValList of tables in the data source, then use methods in the IValList interfaceIGXValList interface and the Val classGXVAL struct 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)IGXColumn interface.
Return Value
ITable object, or null for failure (such as an invalid table name).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
ITable Interface (deprecated)IGXTable interface
createDataConn( )CreateDataConn( ) in the AppLogic class (deprecated)GXAppLogic class
Val classGXVAL struct
IValList interfaceIGXValList interface
Returns an IValListIGXValList of database tables or views that are available to the specified user.
Syntax
public IValList getTables(
String szQualifier,
String szOwner,
String szTable)
HRESULT GetTables(
LPSTR szQualifier,
LPSTR szOwner,
LPSTR szTable,
IGXValList **ppTableList);
szQualifier. Specify nullNULL. Driver-dependent.
szOwner. Specify nullNULL, or a schema name, which returns tables for that schema.
szTable. Table or view name with wildcards, or nullNULL 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:
ppTableList. Pointer to the IGXValList object that contains the returned list of table names. When AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use getTables( )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 interfaceIGXValList interface and the Val classGXVAL struct to iterate through the table names obtained and determine which table(s) to work with. Thereafter, use CreateDataConn( ) 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).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
ITable Interface (deprecated)IGXTable interface
createDataConn( )CreateDataConn( ) in the AppLogic class (deprecated)GXAppLogic class
IValList interfaceIGXValList interface
Creates an ICallableStmtIGXCallableStmt object that contains a call to a stored procedure.
Syntax
public ICallableStmt prepareCall(
int dwFlags,
IQuery pQuery,
ITrans pTrans,
IValList pProps);
HRESULT PrepareCall(
DWORD dwFlags,
IGXQuery *pQuery,
IGXTrans *pTrans,
IGXValList *pProps,
IGXCallableStmt **ppCall);
pQuery. The IQueryPointer to the IGXQuery object that contains the call to a stored procedure. The stored procedure call should have been specified with the setSQL( )SetSQL( ) method in the IQueryIGXQuery interface.
pTrans. ITrans Pointer to an IGXTrans object that contains the transaction associated with this callable statement, or nullNULL for no transaction. This same ITransIGXTrans object must then be passed to the execute( )Execute( ) method of the ICallableStmtIGXCallableStmt interface.
ppCall. Pointer to the returned IGXCallableStmt object. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use prepareCall( )PrepareCall( ) to create a ICallableStmtIGXCallableStmt object that contains a call to a stored procedure. After creating the callable statement, run it by calling execute( )Execute( ) in the ICallableStmtIGXCallableStmt interface.
- Before calling prepareCall( )PrepareCall( ), the AppLogic must create a query by first calling createQuery( )createQuery( ) in the AppLogic class (deprecated)GXAppLogic class to create the IQueryIGXQuery object, then using the setSQL( )SetSQL( ) method in the IQuery Interface (deprecated)IGXQuery interface 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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
ICallableStmt Interface (deprecated)IGXCallableStmt interface
Prepares a flat query object for subsequent execution.
Syntax
public IPreparedQuery prepareQuery(
int dwFlags,
IQuery pQuery,
ITrans pTrans,
IValList pProps)
HRESULT PrepareQuery(
DWORD dwFlags,
IGXQuery *pQuery,
IGXTrans *pTrans,
IGXValList *pProps,
IGXPreparedQuery **ppPQuery);
pQuery. IQueryPointer to the IGXQuery object that contains the query or statement to execute.
pTrans. ITrans Pointer to the IGXTrans object that contains the transaction to which this query applies, or nullNULL. This same Include File object must then be passed to the execute( )Execute( ) method of the IPreparedQueryIGXPreparedQuery interface.
ppPQuery. Pointer to the IGXPreparedQuery object that contains the returned prepared query. When AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use prepareQuery( )PrepareQuery( ) to prepare the query, then execute the prepared query using execute( )Execute( ) in the IPreparedQuery Interface (deprecated)IGXPreparedQuery interface. An application can also use prepareQuery( )PrepareQuery( ) with result set buffering to pre-fetch result set data efficiently from a back-end database.
Rule
Before calling prepareQuery( )PrepareQuery( ), AppLogic must create a query by first calling createQuery( )createQuery( ) in the AppLogic class (deprecated)AppLogic class (deprecated) to create the IQueryIGXQuery object, then using methods in the IQuery Interface (deprecated)IGXQuery interface to define the query.
Return Value
IPreparedQuery object, or null for failure.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
IPreparedQuery Interface (deprecated)IGXPreparedQuery interface
IQuery Interface (deprecated)IGXQuery interface
ITrans Interface (deprecated)IGXTrans interface
IValList interfaceIGXValList interface
createDataConn( )CreateDataConn( ) in the AppLogic class (deprecated)GXAppLogic class
Specifies registry values for the current database connection.
Syntax
public int setConnProps(
IValList pProps)
HRESULT SetConnProps(
IGXValList *pProps);
pProps. A pointer to the IValListIGXValList 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( )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( )GetConnProps( ).
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
getConnProps( )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 IGXDataConnSet interface represents a collection of data connections and associated query names. It is used in conjunction with loading a query file.
Use IDataConnSet IGXDataConnSet 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( )CreateDataConnSet( ) in the AppLogic class (deprecated) to create an empty IDataConnSet IGXDataConnSet 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 IGXDataConnSet is part of the Data Access Engine (DAE) service.
To create an instance of the IDataConnSet IGXDataConnSet interface, use createDataConnSet( )CreateDataConnSet( ) in the AppLogic class (deprecated)GXAppLogic class, as shown in the following example:.
connSet = createDataConnSet();
Package Include File
com.kivasoftgxidata.h
Associates a query name with a data connection object and adds it to the IDataConnSet IGXDataConnSet object.
Related Topics
createDataConnSet( )CreateDataConnSet( ) in the AppLogic class (deprecated)GXAppLogic class
Associates a query name with a data connection object and adds it to the IDataConnSet IGXDataConnSet object.
Syntax
public int addConn(
String pQueryName,
IDataConn pConn)
HRESULT AddConn(
LPSTR pQueryName,
IGXDataConn *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 IDataConnSetIGXDataConnSet object.
- The AppLogic must first create the data connection object using createDataConn( )CreateDataConn( ) in the AppLogic class (deprecated)GXAppLogic class.
- Duplicate query names are not permitted.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
createDataConnSet( )CreateDataConnSet( ) in the AppLogic class (deprecated)GXAppLogic class
The IEnumObjectIGXEnumObject interface represents an enumeration object that contains IObjectIGXObject instances. Some methods that return a list of objects, such as enumEvents( )EnumEvents( ) in the IAppEventMgrIGXAppEventMgr interface, return an IEnumObjectIGXEnumObject object.
The IEnumObjectIGXEnumObject interface defines methods for counting and accessing the IObjectIGXObject instances in an IEnumObjectIGXEnumObject.
Package Include File
com.kivasoftgxienum.h
Related Topics
enumEvents( )EnumEvents( ) in the IAppEventMgr InterfaceIGXAppEventMgr interface
Returns the number of IObjectIGXObject instances in an IEnumObjectIGXEnumObject.
HRESULT EnumCount(
ULONG *pCount);
pCount. Pointer to the variable that contains the returned number of IGXObject instances in the IGXEnumObject.
Usage
Use enumCount( )EnumCount( ) to determine the number of objects to process before iterating through the IObjectIGXObject instances in the IEnumObjectIGXEnumObject.
Return Value
The number of objects in an IEnumObject.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
In the following example, enumEvents( )EnumEvents( ) returns all the application events registered with the iPlanet Application Server in an IEnumObjectIGXEnumObject. The enumCount( )EnumCount( ) method is used in conjunction with enumNext( )EnumNext( ) and enumReset( )EnumReset( ) to access objects in the IEnumObjectIGXEnumObject.
Related Topics
enumEvents( )EnumEvents( ) in the IAppEventMgr InterfaceIGXAppEventMgr interface
Returns the next IObjectIGXObject instance in an IEnumObjectIGXEnumObject.
Syntax
public IObject enumNext()
HRESULT EnumNext(
IGXObject **ppNext);
ppNext. Pointer to the returned IGXObject object. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use enumNext( )EnumNext( ) in conjunction with enumCount( )EnumCount( ) and enumReset( )EnumReset( ) to iterate through an IEnumObjectIGXEnumObject.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
In the following example, enumEvents( )EnumEvents( ) returns all the application events registered with the iPlanet Application Server in an IEnumObjectIGXEnumObject. The enumNext( )EnumNext( ) method is used in conjunction with enumCount( )EnumCount( ) and enumReset( )EnumReset( ) to access objects in the IEnumObjectIGXEnumObject.
Related Topics
enumEvents( )EnumEvents( ) in the IAppEventMgr InterfaceIGXAppEventMgr interface
Resets to the first IObjectIGXObject instance in an IEnumObjectIGXEnumObject.
Syntax
public int enumReset(
int dwFlags)
HRESULT EnumReset(
DWORD dwFlags);
Usage
Use enumReset( )EnumReset( ) before iterating through an IEnumObjectIGXEnumObject. Doing so ensures that iteration begins at the first IObjectIGXObject instance in the IEnumObjectIGXEnumObject.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
enumEvents( )EnumEvents( ) in the IAppEventMgr InterfaceIGXAppEventMgr 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 IErrorIGXError 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, IErrorIGXError handles database errors only.
Use the methods in the IErrorIGXError interface to get error codes and messages returned by a database.
The IErrorIGXError interface is implemented by the IDataConnIGXDataConn object. To use it, cast IDataConnIGXDataConn to the IErrorIGXError interface, as shown in the following example:
conn->QueryInterface(IID_IGXError, (LPVOID *) &error);
Package Include File
com.kivasoft gxierror.h
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()
HRESULT getErrorCode(
LPSTR pCode,
ULONG nSize);
pCode. Pointer to the buffer allocated by the client to store the returned error code.
nSize. The size of the buffer to store the error code. 256 bytes is usually sufficient. If the error code string exceeds the specified size, it is truncated.
Usage
Use getErrorCode( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
getErrorCodeNum( )GetErrorCodeNum( )
getErrorMessage( )GetErrorMessage( )
getErrorFacility( )GetErrorFacility( )
Returns the current error code as a number.
Syntax
public int getErrorCodeNum()
HRESULT getErrorCodeNum(
DWORD *nCode);
nCode. Pointer to the variable allocated by the client to store the returned error code.
Usage
Use getErrorCodeNum( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
getErrorCode( )GetErrorCode( )
getErrorMessage( )GetErrorMessage( )
getErrorFacility( )GetErrorFacility( )
Returns the message associated with the current error code.
Syntax
public String getErrorMessage(
String pCode)
HRESULT getErrorCode(
LPSTR pCode,
LPSTR pMessage,
ULONG nSize);
pCode. Specify NULLany string.
pMessage. Pointer to the buffer allocated by the client to store the returned message.
nSize. The size of the buffer to store the error message.
Usage
Use getErrorMessage( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
getErrorCode( )GetErrorCode( )
getErrorCodeNum( )GetErrorCodeNum( )
getErrorFacility( )GetErrorFacility( )
Returns a description of the facility that generated an error code.
Syntax
public String getErrorFacility()
HRESULT getErrorFacility(
LPSTR pDescription,
ULONG nSize);
pDescription. Pointer to the buffer allocated by the client to store the returned string description.
nSize. The size of the buffer to store the string description. If the string exceeds the specified size, it is truncated.
Usage
Use getErrorFacility( )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( )GetErrorFacility( ): "ODBC DAD".
Return Value
The description of the facility that generated the current error code.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
getErrorCode( )GetErrorCode( )
getErrorCodeNum( )GetErrorCodeNum( )
getErrorMessage( )GetErrorMessage( )
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 IGXHierQuery interface represents a hierarchical query. IHierQuery IGXHierQuery 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 IGXQuery object containing data selection criteria. The IHierQuery IGXHierQuery object contains the definition of the hierarchical structure of parent-child relationships among IQuery IGXQuery objects.
To use a hierarchical query, the AppLogic first creates each individual query and defines its selection criteria. Next, it creates theIHierQuery IGXHierQuery object and calls addQuery( )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( )Execute( ) method to run the hierarchical query on the target data source and retrieve a hierarchical result set in an IHierResultSetIGXHierResultSet object.
Alternatively, the AppLogic can load a hierarchical query stored in a file. For more information, see loadHierQuery( )LoadHierQuery( ) and createDataConnSet( )CreateDataConnSet( ) in the AppLogic class (deprecated)GXAppLogic class.
To create an instance of the IHierQuery IGXHierQuery interface, use createHierQuery( )createHierQuery( ) in the AppLogic class (deprecated)GXAppLogic class., as shown in the following example:
Package Include File
com.kivasoft gxidatap.h
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.
// Create the flat query IQuery qry = createQuery(); qry.setTables("CTLusers"); qry.setFields("loginName, Password, AccessLevel") query.setWhere("UserId"+"="+wantedUser.hashCode()); // Create the hierarchical query IHierQuery hqry = createHierQuery(); hqry.addQuery(qry, conn, "USERS", "", ""); // Execute the hierarchical query IHierResultSet hrs = hqry.execute(0, 0, null); // Process rows in result set . . . if(hrs.getRowNumber("USERS")!=0) "> Example 2
Related Topics
createHierQuery( )createHierQuery( ) in the AppLogic class (deprecated)GXAppLogic class
"Writing Hierarchical Queries"
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)
HRESULT AddQuery(
IGXQuery *pQuery,
IGXDataConn *pConn,
LPSTR szAlias,
LPSTR szParent,
LPSTR szJoin);
pQuery. IQuery Pointer to the IGXQuery object that contains the flat query object to append as a child to the parent query.
pConn. IDataConn Pointer to the IGXDataConn 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( )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'");
HRESULT hr = hqr->AddQuery(pQryEMP, pConn, "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( )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( )AddQuery( ) calls, is limited only by system resources.
- The AppLogic must first create the data connection using createDataConn( )CreateDataConn( ) in the AppLogic class (deprecated)GXAppLogic class.
- The AppLogic must then create the specified child query using createQuery( )createQuery( ) in the AppLogic class (deprecated)GXAppLogic class. A separate child query must exist for every level of data.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
// Create the hier query IGXHierQuery *pHq=NULL; if(((hr=CreateHierQuery(&pHq))==GXE_SUCCESS)&&pHq) { // Add a query pHq->AddQuery(pQuery, pConn, "SelCusts", "", "");
Related Topics
createHierQuery( )createHierQuery( ) in the AppLogic class (deprecated)GXAppLogic class
IQuery Interface (deprecated)IGXQuery interface
IDataConn Interface (deprecated)IGXDataConn interface
"Writing Hierarchical Queries"
Removes a child query from its parent query.
Syntax
public int delQuery(
String szName)
HRESULT DelQuery(
LPSTR szName);
szName. Name of the child query to remove.
Usage
Use delQuery( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
createHierQuery( )createHierQuery( ) in the AppLogic class (deprecated)AppLogic class (deprecated)
loadHierQuery( ) in the AppLogic class (deprecated)
"Writing Hierarchical Queries"
Executes a hierarchical query and returns a hierarchical result set.
Syntax
public IHierResultSet execute(
int dwFlags,
int dwTimeout,
IValList pProps)
HRESULT Execute(
DWORD dwFlags,
DWORD dwTimeout,
IGXValList *pProps,
IGXHierResultSet **ppHierResultSet);
dwFlags. Specifies flags used to execute this hierarchical query.
- For synchronous operations, the default, specify zero or GX_DA_EXECUTEQUERY_FLAGS.GX_DA_EXEC_SYNC.
- For asynchronous operations, specify GX_DA_EXECUTEQUERY_FLAGS.GX_DA_EXEC_ASYNC.
- To activate result set buffering, specify GX_DA_EXECUTEQUERY_FLAGS.GX_DA_RS_BUFFERING.
The AppLogic can pass both result set buffering and either synchronous or asynchronous queries as the flags parameter, as shown in the following example:
(GX_DA_EXECUTEQUERY_FLAGS.GX_DA_EXEC_ASYNC | GX_DA_EXECUTEQUERY_FLAGS.GX_DA_RS_BUFFERING).
pProps. IValListPointer to the IGXValList object that contains query properties, or nullNULL for no properties. After instantiating an object of the IValList interfaceIGXValList interface, set any of the following properties:
- RS_BUFFERING turns on result set buffering when set to "TRUE".
- RS_INIT_ROWS specifies the initial size of the buffer, in number of rows. If the result set size exceeds this setting, a fetchNext( )FetchNext( ) call will return the error GX_DA_FETCHNEXT_RESULTS.GX_DA_BUFFER_EXCEEDEDGX_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( )FetchNext( ) call will return the error GX_DA_FETCHNEXT_RESULTS.GX_DA_BUFFER_EXCEEDEDGX_DA_BUFFER_EXCEEDED.
- RS_MAX_SIZE specifies the maximum number of bytes for the buffer.
If RS_BUFFERING is enabled and if the optional parameters are not specified, the global values in the registry are used instead..
ppHierResultSet. Pointer to the IGXHierResultSet object that contains the returned result of the hierarchical query. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
After constructing a hierarchical query using addQuery( )AddQuery( ), the AppLogic uses execute( )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( )AddQuery( ).
Return Value
IHierResultSet object that contains the result set of the hierarchical query, or null for failure (such as invalid parameters).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
createHierQuery( )createHierQuery( ) in the AppLogic class (deprecated)AppLogic class (deprecated)
loadHierQuery( ) in the AppLogic class (deprecated)
IHierResultSet Interface (deprecated)IGXHierResultSet interface
IValList interfaceIGXValList interface
"Writing Hierarchical Queries"
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 IHierResultSetIGXHierResultSet interface represents a hierarchical result set retrieved by a hierarchical query. IHierResultSetIGXHierResultSet 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( )EvalOutput( ) in the AppLogic class (deprecated)GXAppLogic class.
IHierResultSetIGXHierResultSet is part of the Data Processing Engine (DPE) service. To create an instance of IHierResultSetIGXHierResultSet, use execute( )Execute( ) in the IHierQuery Interface (deprecated)IGXHierQuery interface, as shown in the following example:
hrs = hqry.execute(0, 0, null);
hr = hqry->Execute(0, 0, NULL, &hrs);
Package Include File
com.kivasoft gxidatap.h
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( ) createHierQuery( ) in the AppLogic class (deprecated)GXAppLogic class
IHierQuery Interface (deprecated)IGXHierQuery interface
"Getting Data From a Flat Query's Result Set"
Returns the total number of rows retrieved so far from the data source for the specified child query.
Syntax
public int count(
String qryName)
HRESULT Count(
LPSTR qryName,
ULONG *nRows);
qryName. Name of the child query that generated the result set.
nRows. Pointer to the variable that contains the returned number of rows in the result set.
Usage
Use count( )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( )Count( ) to determine the current maximum number of rows to process.
Tip
If result set buffering is enabled, the AppLogic can use count( )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).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
createHierQuery( ) createHierQuery( ) in the AppLogic class (deprecated)GXAppLogic class
IHierQuery Interface (deprecated)IGXHierQuery interface
"Getting Data From a Flat Query's Result Set"
Returns the column definition for the column with the specified name in the specified child query.
Syntax
public IColumn getColumn(
String qryName,
String colName)
HRESULT GetColumn(
LPSTR qryName,
LPSTR colName,
IGXColumn **ppCol);
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).
ppCol. Pointer to the IGXColumn object that contains the returned column definition. When AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use getColumn( )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)IGXColumn interface 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.
- The specified column name must exist in the result set.
Tips
- Use getColumnByOrd( )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( )SetFields( ) in the IQuery Interface (deprecated)IGXQuery interface 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).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
// Obtain column information for UserID field IColumn col; col = hrs.getColumn("USERS", "UserID") . . . process column info using IColumn methods . . .
Related Topics
createHierQuery( ) createHierQuery( ) in the AppLogic class (deprecated)GXAppLogic class
IHierQuery Interface (deprecated)IGXHierQuery interface
IColumn Interface (deprecated)IGXColumn interface
"Getting Data From a Flat Query's Result Set"
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)
HRESULT GetColumnByOrd(
LPSTR qryName,
ULONG colIndex,
IGXColumn **ppCol);
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.
ppCol. Pointer to the IGXColumn object that contains the returned column definition. When AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use getColumnByOrd( )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)IGXColumn interface 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.
- The specified column position must exist in the result set.
Tip
Use getColumn( )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).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
// Obtain column information for UserID field
IColumn 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 . . .
// Not shown here, execution of hierarchical query
// that retrieves the hierarchical resultset.
hr = hrs->GetColumnByOrd("INVOICES", 1, &col);
// Call column methods, such as IGXColumn::GetName() here.
Related Topics
createHierQuery( ) createHierQuery( ) in the AppLogic class (deprecated)GXAppLogic class
IHierQuery Interface (deprecated)IGXHierQuery interface
IColumn Interface (deprecated)IGXColumn interface
"Getting Data From a Flat Query's Result Set"
Returns the result set for a specified child query.
Syntax
public IResultSet getResultSet(
String qryName)
HRESULT GetResultSet(
LPSTR qryName,
IGXResultSet **ppResultSet);
qryName. Name of the child query that generated the result set to retrieve.
ppResultSet. Pointer to the IGXResultSet object that contains the returned result set. When AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use getResultSet( )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)IGXResultSet interface 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).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
// Look up list of customers matching criteria from database
IHierResultSet 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");
// Look up list of customers matching criteria from database
IGXHierResultSet *pHRset=NULL;
if(((hr=LookupCustomer(pSsn, pLastName, pFirstName, pAcctNum,
&pHRset))==GXE_SUCCESS)&&pHRset) {
// Check the result set to see if any customers are found
if(((hr=pHRset->GetResultSet("SelCusts",
&pRset))==GXE_SUCCESS)&&pRset) {
Related Topics
"Getting Data From a Flat Query's Result Set"
Returns the number of the current row for the specified child query in the hierarchical result set.
Syntax
public int getRowNumber(
String qryName)
HRESULT GetRowNumber(
LPSTR qryName,
ULONG *pOrd);
qryName. Name of the child query that generated the result set.
pOrd. Pointer to the variable that contains the returned row number for the current row.
Usage
When iterating through rows in a child set, use getRowNumber( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
// Create the hierarchical query
IHierQuery 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( ) createHierQuery( ) in the AppLogic class (deprecated)GXAppLogic class
IHierQuery Interface (deprecated)IGXHierQuery interface
"Getting Data From a Flat Query's Result Set"
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)
HRESULT GetValueDateString(
LPSTR qryName,
LPSTR colName,
LPSTR pVal,
ULONG nVal);
qryName. Name of the child query that generated the result set.
colName. Name of the column from which to retrieve the date.
pVal. Pointer to the variable that contains the returned column value.
Usage
Use getValueDateString( )GetValueDateString( ) to retrieve date values from the result set for subsequent processing. The following is an example of the format in which getValueDateString( )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).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
IGXHierResultSet *hrs = NULL;
// Not shown here, execution of hierarchical query
// that retrieves the hierarchical resultset.
hr = hrs->GetValueDateString("INVOICES", "ShipDate", buffer, sizeof(buffer));
Related Topics
getValueDouble( )GetValueDouble( )
getValueString( )GetValueString( )
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)
HRESULT GetValueDouble(
LPSTR qryName,
LPSTR colName,
double *pVal);
qryname. Name of the child query that generated the result set.
colName. Name of the column from which to retrieve the double value.
pVal. Pointer to the variable that contains the returned column value.
Usage
Use getValueDouble( )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).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
getValueDateString( )GetValueDateString( )
getValueString( )GetValueString( )
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)
HRESULT GetValueInt(
LPSTR qryName,
LPSTR colName,
ULONG *pVal);
qryname. Name of the child query that generated the result set.
colName. Name of the column from which to retrieve the value.
pVal. Pointer to the variable that contains the returned column value.
Usage
Use getValueInt( )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).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
getValueDateString( )GetValueDateString( )
getValueDouble( )GetValueDouble( )
getValueString( )GetValueString( )
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)
HRESULT GetValueString(
LPSTR qryName,
LPSTR colName,
LPSTR pVal,
ULONG nVal);
qryname. Name of the child query that generated the result set.
colName. Name of the column from which to retrieve the value.
pVal. Pointer to the variable that contains the returned column value.
Usage
Use getValueString( )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).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
IGXHierResultSet *hrs = NULL;
// Not shown here, execution of hierarchical query
// that retrieves the hierarchical resultset.
hr = hrs->GetValueString("CUSTOMERS", "Country", buffer, sizeof(buffer));
StreamResult("The customer lives in the country of ");
Related Topics
getValueDateString( )GetValueDateString( )
getValueDouble( )GetValueDouble( )
Moves to the next row for the specified child query in the result set.
Syntax
public int moveNext(
String qryName)
HRESULT MoveNext(
LPSTR qryName);
qryName. Name of the child query that generated the result set.
Usage
Use moveNext( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds. If the target row is out of range, HRESULT is set to -1.
Related Topics
createHierQuery( ) createHierQuery( ) in the AppLogic class (deprecated)GXAppLogic class
IHierQuery Interface (deprecated)IGXHierQuery interface
"Getting Data From a Flat Query's Result Set"
Moves to the specified row for the specified child query in the result set.
Syntax
public moveTo(
String qryName,
int nRow)
HRESULT MoveTo(
LPSTR qryName,
ULONG 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( )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).
HRESULT, which is set to GXE_SUCCESS if the method succeeds. If the target row is out of range, HRESULT is set to -1.
Related Topics
createHierQuery( ) createHierQuery( ) in the AppLogic class (deprecated)GXAppLogic class
IHierQuery Interface (deprecated)IGXHierQuery interface
"Getting Data From a Flat Query's Result Set"
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 ILockIGXLock 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.
- 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.
The ILockIGXLock interface defines methods for locking and unlocking objects. It also defines a method for changing the lock mode.
Package Include File
com.kivasoft gxilock.h
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);
HRESULT ChangeMode(
DWORD dwOldMode,
int dwNewMode,
LPBYTE pID
ULONG 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( )ChangeMode( ) to change a lock on an object.
Return Value
An integer indicating success or failure of the lock mode change operation.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Syntax
public int lock(
int dwFlags,
byte[] pID,
int nSize);
HRESULT Lock(
DWORD dwFlags,
LPBYTE pID
ULONG 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( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds, or an error code, such as GXE_FAIL on failure.
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 it
ILock 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 node
ret = l.unlock(GXLOCK.GXLOCK_EXCL, null, 0);
if (ret != GXE.SUCCESS)
log("unlock error");
IGXState2 *marketnews = NULL;
HRESULT hr = cacheroot->GetStateChild("mktnews", &marketnews);
if (hr != GXE_SUCCESS || !marketnews)
return;
// we expect marketnews state node to be accessed concurrently
IGXLock *l = null;
hr = marketnews->QueryInterface(IID_IGXLock, (LPVOID *)&l);
if (hr != GXE_SUCCESS || !l)
{
marketnews->Release();
return;
}
hr = l->Lock(GXLOCK_EXCL, NULL, 0);
if (hr != GXE_SUCCESS)
{
marketnews->Release();
l->Release();
Log("lock error");
return;
}
// we now have the node locked in exclusive mode
// ..... do work ..........
// and unlock the node
hr = l->Unlock(GXLOCK.GXLOCK_EXCL, NULL, 0);
if (hr != GXE_SUCCESS)
{
marketnews->Release();
l->Release();
Log("unlock error");
return;
}
Related Topics
AppLogicGXAppLogic or ISession2GXSession2 classes
Unlocks a previously locked object.
Syntax
public int unlock(
int dwFlags,
byte[] pID,
int nSize);
HRESULT Unlock(
DWORD dwFlags,
LPBYTE pID
ULONG 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( )Unlock( ) to remove a lock on an object.
Return Value
An integer indicating success or failure of the unlock operation.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
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 it
ILock 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 node
ret = l.unlock(GXLOCK.GXLOCK_EXCL, null, 0);
if (ret != GXE.SUCCESS)
log("unlock error");
IGXState2 *marketnews = NULL;
HRESULT hr = cacheroot->GetStateChild("mktnews", &marketnews);
if (hr != GXE_SUCCESS || !marketnews)
return;
// we expect marketnews state node to be accessed concurrently
IGXLock *l = null;
hr = marketnews->QueryInterface(IID_IGXLock, (LPVOID *)&l);
if (hr != GXE_SUCCESS || !l)
{
marketnews->Release();
return;
}
hr = l->Lock(GXLOCK_EXCL, NULL, 0);
if (hr != GXE_SUCCESS)
{
marketnews->Release();
l->Release();
Log("lock error");
return;
}
// we now have the node locked in exclusive mode
// ..... do work ..........
// and unlock the node
hr = l->Unlock(GXLOCK.GXLOCK_EXCL, NULL, 0);
if (hr != GXE_SUCCESS)
{
marketnews->Release();
l->Release();
Log("unlock error");
return;
}
Related Topics
AppLogicGXAppLogic or ISession2GXSession2 classes
The IMailboxIGXMailBox interface represents an electronic mailbox used for communicating with incoming and outgoing electronic mail. IMailboxIGXMailBox 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 IMailboxIGXMailbox interface, use createMailbox( )CreateMailbox( ) in the AppLogic class (deprecated)GXAppLogic class, as shown in the following example:
IMailbox mb = createMailbox("SMTPHostName", "myUserName",
"pass7878", "myEmailAddr@myOrg.com");
CreateMailbox(pSendHost,pUser,pPswd,pUserAddr,
Package Include File
com.kivasoft gximailbox.h
Related Topics
createMailbox( )CreateMailbox( ) in the AppLogic class (deprecated)GXAppLogic class
Closes an open electronic mailbox session.
Usage
Use close( )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( )Close( ) terminates both sessions.
Closing a session does not terminate the IMailboxIGXMailbox object. The AppLogic can later reopen a session using open( )Open( ).
Rule
The AppLogic can only close a mailbox session that is open.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
// Define the string parameters that will be passed
String 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)
// Define the string parameters that will be passed
LPSTR SendHost = "smtp.kivasoft.com";
LPSTR RecvHost = "pop.kivasoft.com";
LPSTR pPswd = "eugenesSecretPassword";
LPSTR pUserAddr = "eugene@kivasoft.com";
LPSTR pSendTo[] = {"friend@otherhost.net", NULL};
LPSTR pMesg = "Hi Friend, How are you?";
// Create an IGXMailbox instance
if ((hr = CreateMailbox(pSendHost,pUser,pPswd,pUserAddr,
&pSendMBox)) == NOERROR && pSendMBox != NULL)
// Open the mailbox to send the message
if ((hr = pSendMBox->Open(OPEN_SEND)) == NOERROR)
pSendMBox->Send(pSendTo, pSendMesg);
createMailbox( )CreateMailbox( ) in the AppLogic class (deprecated)GXAppLogic class
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( )Open( ) to explicitly open a session with the mail server after instantiating the IMailboxIGXMailbox object. Alternatively, the AppLogic can open a session after having closed a previous session using close( )Close( ).
Depending on the setting of the dwFlag parameter, open( )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( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
// Define the string parameters that will be passed
String 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))
// Define the string parameters that will be passed
LPSTR SendHost = "smtp.kivasoft.com";
LPSTR RecvHost = "pop.kivasoft.com";
LPSTR pPswd = "eugenesSecretPassword";
LPSTR pUserAddr = "eugene@kivasoft.com";
LPSTR pSendTo[] = {"friend@otherhost.net", NULL};
LPSTR pMesg = "Hi Friend, How are you?";
// Create an IGXMailbox instance
if ((hr = CreateMailbox(pSendHost,pUser,pPswd,pUserAddr,
&pSendMBox)) == NOERROR && pSendMBox != NULL)
// Open the mailbox to send the message
if ((hr = pSendMBox->Open(OPEN_SEND)) == NOERROR)
pSendMBox->Send(pSendTo, pSendMesg);
createMailbox( )CreateMailbox( ) in the AppLogic class (deprecated)GXAppLogic class
Retrieves electronic mail messages from the inbox.
Syntax
public IValList retrieve(
boolean bLatest,
boolean bDelete)
HRESULT Retrieve(
BOOL bLatest,
BOOL bDelete
IGXValList **ppMsgs);
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.
ppMsgs. Pointer to the IGXValList object that contains the message strings. The keys are the message numbers. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use retrieve( )Retrieve( ) to get unread messages from the inbox. Once retrieved, messages are marked as READ.
Rule
To use retrieve( )Retrieve( ), the AppLogic must have first opened the mailbox session using open( )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( )RetrieveReset( ) to undo changes (deletes, read flags) to messages in the inbox.
Return Value
IValList that contains the retrieved messages, or null for failure.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
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
// Only check messages received after the last open
// Remove retrieved messages from the mail server
if ((hr = CreateMailbox(host,user,passwd,useraddr,
&pRecvMBox)) == NOERROR && pRecvMBox != NULL)
// Open a mailbox to receive new messages
if ((hr = pRecvMBox->Open(OPEN_RECV)) == NOERROR)
// Count the number of unretrieved messages
if((NumMsgs = pRecvMBox->RetrieveCount()) > 0)
if((pRecvMBox->Retrieve(Latest, Delete,
// Use IGXValList methods to iterate through
// the returned IGXValList. The keys in the
// IGXValList are the message numbers. The
// values are the email messages as strings
createMailbox( )CreateMailbox( ) in the AppLogic class (deprecated)GXAppLogic class
Counts the number of unread electronic mail messages in the inbox.
Syntax
public int retrieveCount()
Usage
Before calling retrieve( )Retrieve( ), use retrieveCount( )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( )RetrieveCount( ) to determine the maximum number of iterations required to process all available inbox messages.
Rule
To use retrieveCount( )RetrieveCount( ), the AppLogic must have first opened the mailbox session using open( )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( )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
// Only check messages received after the last open
// Remove retrieved messages from the mail server
if ((hr = CreateMailbox(host,user,passwd,useraddr,
&pRecvMBox)) == NOERROR && pRecvMBox != NULL)
// Open a mailbox to receive new messages
if ((hr = pRecvMBox->Open(OPEN_RECV)) == NOERROR)
// Count the number of unretrieved messages
if((NumMsgs = pRecvMBox->RetrieveCount()) > 0)
if((pRecvMBox->Retrieve(Latest, Delete,
// Use IGXValList methods to iterate through
// the returned IGXValList. The keys in the
// IGXValList are the message numbers. The
// values are the email messages as strings
createMailbox( )CreateMailbox( ) in the AppLogic class (deprecated)GXAppLogic class
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( )RetrieveReset( ) to undo any changes made as a result of retrieving inbox messages with retrieve( )Retrieve( ).
- To use retrieveReset( )RetrieveReset( ), the AppLogic must have first opened the mailbox session using open( )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( )RetrieveReset( ), the AppLogic must first call retrieve( )Retrieve( ).
- To abandon changes made with retrieve( )Retrieve( ), AppLogic must call retrieveReset( )RetrieveReset( ) before calling close( )Close( ) or terminating the session.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
createMailbox( )CreateMailbox( ) in the AppLogic class (deprecated)GXAppLogic class
Sends an electronic mail message to one or more mail addresses.
Syntax
public int send(
String[] ppTo,
String pMesg)
HRESULT Send(
LPSTR *ppTo,
LPSTR 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( )Send( ), the AppLogic must have first opened the mailbox session using open( )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( )Send( ) method automatically includes the FROM: address that the AppLogic specified in the pUserAddr parameter of createMailbox( )CreateMailbox( ) in the AppLogic class (deprecated).
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
// Define the string parameters that will be passed
String 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))
// Define the string parameters that will be passed
LPSTR SendHost = "smtp.kivasoft.com";
LPSTR RecvHost = "pop.kivasoft.com";
LPSTR pPswd = "eugenesSecretPassword";
LPSTR pUserAddr = "eugene@kivasoft.com";
LPSTR pSendTo[] = {"friend@otherhost.net", NULL};
LPSTR pMesg = "Hi Friend, How are you?";
// Create an IGXMailbox instance
if ((hr = CreateMailbox(pSendHost,pUser,pPswd,pUserAddr,
&pSendMBox)) == NOERROR && pSendMBox != NULL)
// Open the mailbox to send the message
if ((hr = pSendMBox->Open(OPEN_SEND)) == NOERROR)
pSendMBox->Send(pSendTo, pSendMesg);
Related Topics
open( )Open( ),
retrieve( )Retrieve( )
createMailbox( )CreateMailbox( ) in the AppLogic class (deprecated)GXAppLogic class
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 IGXOrder interface represents the current processing status of an asynchronous operation. IOrder IGXOrder 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 flagsdwFlags parameter in any of the following methods:
- executeQuery( )ExecuteQuery( ) in the IDataConn Interface (deprecated)IGXDataConn interface
- addRow( )AddRow( ), deleteRow( )DeleteRow( ), or updateRow( )UpdateRow( ) in the ITable Interface (deprecated)IGXTable interface
To create an instance of the IOrderIGXOrder interface for an asynchronous query, use getOrder( )GetOrder( ) in the IResultSet Interface (deprecated)IGXResultSet interface, as shown in the following example:.
Package Include File
com.kivasoft gxiorder.h
Returns the processing status of the asynchronous operation on the database server: active, done, canceled, or unknown.
Related Topics
executeQuery( )ExecuteQuery( ) in the IDataConn Interface (deprecated)IGXDataConn interface
getOrder( )GetOrder( ) in the IResultSet Interface (deprecated)IGXResultSet interface
GXWaitForOrder( ) helper function
Returns the processing status of the asynchronous operation.
Syntax
public getStateIOrder getState()
HRESULT GetState(
DWORD *pdwState,
DWORD *pdwResult,
ULONG *pGuess);
pdwState. Pointer to the variable that contains the returned status code. The variable is set to one of the following:
Constant
Description
The asynchronous operation has been completely processed. Check the pdwResult variable to see if the operation completed with a result of success or failure.
pdwResult. Pointer to the variable that contains the returned result, which is the HRESULT return value of the operation (which is what is obtained if the operation were called synchronously.)
pGuess. Pointer to the variable that contains the returned estimate about the current completion percentage of the operation. iPlanet Application Server internal use only.
Usage
Use getState( )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:
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
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");
if (NewRequestAsync(asyncGUIDStr, m_pValIn,
m_pValOut, 0, &pOrder) == GXE_SUCCESS)
Log("Successfully invoked async AppLogic\n");
// wait for async applogic to finish (max 100 seconds)
hr = GXWaitForOrder(&pOrder, 1, &nOrder, m_pContext, 100);
return Result("Error in executing async request:
order wait returned an error");
pOrder->GetState(NULL, &ReqResult, NULL);
return Result("Error in executing async
Log("Failed to invoke async AppLogic\n");
Related Topics
executeQuery( )ExecuteQuery( ) in the IDataConn Interface (deprecated)IGXDataConn interface
getOrder( )GetOrder( ) in the IResultSet Interface (deprecated)IGXResultSet interface
GXWaitForOrder( ) helper function
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 IPreparedQueryIGXPreparedQuery interface represents a prepared flat query. An IPreparedQueryIGXPreparedQuery 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.
- Specify a set of parameter values.
- Specify another set of parameter values.
- Execute the prepared query.
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.
To create an instance of the IPreparedQuery IGXPreparedQuery interface, use prepareQuery( )PrepareQuery( ) in the IDataConn Interface (deprecated)IGXDataConn interface., as shown in the following example:
pqry = conn.prepareQuery(0, qry, null, null);
Package Include File
com.kivasoft gxidata.h
Example
// Create the data connection
conn = 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( )PrepareQuery( ) in the IDataConn Interface (deprecated)IGXDataConn interface
"Using Prepared Database Commands"
Syntax
public IResultSet execute(
int dwFlags,
IValList pParams,
ITrans pTrans,
IValList pProps)
HRESULT Execute(
DWORD dwFlags,
IGXValList *pParams,
IGXTrans *pTrans,
IGXValList *pProps,
IGXResultSet **ppResultSet);
dwFlags. Specifies flags used to execute this prepared query. To activate result set buffering, specify GX_DA_EXECUTEQUERY_FLAGS.GX_DA_RS_BUFFERINGGX_DA_RS_BUFFERING. Otherwise, specify zero.
pParams. IValList Pointer to an IGXValList object that contains parameters to pass to the prepared query. Parameters are used to execute the query.
pTrans. ITrans Pointer to an IGXTrans object that contains the transaction associated with this query, or nullNULL for no transaction.
pProps. IValListPointer to the IGXValList object that contains query properties, or nullNULL for no properties. After instantiating an object of the IValList interfaceIGXValList interface, set any of the following properties:
- RS_BUFFERING turns on result set buffering when set to "TRUE".
- RS_INIT_ROWS specifies the initial size of the buffer, in number of rows. If the result set size exceeds this setting, a fetchNext( )FetchNext( ) call will return the error GX_DA_FETCHNEXT_RESULTS.GX_DA_BUFFER_EXCEEDEDGX_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( )FetchNext( ) call will return the error GX_DA_FETCHNEXT_RESULTS.GX_DA_BUFFER_EXCEEDEDGX_DA_BUFFER_EXCEEDED and result set buffering will be turned off.
- RS_MAX_SIZE specifies the maximum number of bytes for the buffer.
If RS_BUFFERING is enabled and if the optional parameters are not specified, the global values in the registry are used instead.
ppResultSet. Pointer to the IGXResultSet object that contains the returned result set from the callable statement, if the database supports this feature. When AppLogic is finished using the object, call the Close( ) method in the IGXResultSet interface, then call the Release( ) method to release the interface instance.
Usage
Use execute( )Execute( ) to run a prepared query. If the command contains parameters, instantiate an IValList IGXValList object and use setValString( )SetVal( ) or setValInt( )SetValByRef( ) in the IValList interfaceIGXValList interface to specify the parameter values to pass to the command.
Return Value
IResultSet object, or null for failure (such as an invalid parameter).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example 1
// Create the data connection
conn = 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 . . .
IGXPreparedQuery *pPQuery=NULL;
if(((hr=pConn->PrepareQuery(0, pQuery, NULL, NULL, &pPQuery))==GXE_SUCCESS)&&pPQuery) {
if(((hr=pPQuery->Execute(0, pList, NULL, NULL,
&pRset))==GXE_SUCCESS)&&pRset) {
Related Topics
IValList Interface (deprecated)IGXValList interface
ITrans Interface (deprecated)IGXTrans interface
prepareQuery( )PrepareQuery( ) in the IDataConn Interface (deprecated)IGXDataConn interface
"Using Prepared Database Commands"
Specifies the parameters for a prepared query.
Syntax
public int setParams(
int dwFlags
IValList pParams)
HRESULT SetParams(
DWORD dwFlags,
IGXValList *pParams);
pParams. Pointer to an IValListIGXValList object that contains parameters to pass to the prepared query.
Usage
To pass parameters to the prepared query using setParams( )SetParams( ), you must pass NULL for the pParams parameter in execute( )Execute( ).
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
IValList Interface (deprecated)IGXValList interface
ITrans Interface (deprecated)IGXTrans interface
prepareQuery( )PrepareQuery( ) in the IDataConn Interface (deprecated)IGXDataConn interface
"Using Prepared Database Commands"
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 IQueryIGXQuery interface represents a flat query. IQuery IGXQuery provides methods for specifying and obtaining the criteria used to select data from a data source. The AppLogic uses IQuery IGXQuery 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 IGXQuery object using createQuery( )createQuery( ) in the AppLogic class (deprecated)GXAppLogic class.
- Specifies query criteria using methods in the IQueryIGXQuery interface.
- Executes the query, passing the loaded IQuery IGXQuery object to executeQuery( )ExecuteQuery( ) in the IDataConn Interface (deprecated)IGXDataConn interface.
- Processes the result set using methods in the IResultSet Interface (deprecated)IGXResultSet interface.
The AppLogic can also use IQuery IGXQuery 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.
To create an instance of the IQuery IGXQuery interface, use the createQuery( )createQuery( ) method in the AppLogic classGXAppLogic class, as shown in the following example:.
Package Include File
com.kivasoft gxidata.h
Example 1
// Create the flat query object
qry.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 connection
if((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( )createQuery( ) in the AppLogic class (deprecated)GXAppLogic class
executeQuery( )ExecuteQuery( ) in the IDataConn Interface (deprecated)IGXDataConn interface
IResultSet Interface (deprecated)IGXResultSet interface
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()
HRESULT GetFields(
IGXBuffer **ppBuff);
ppBuff. Pointer to the IGXBuffer object that contains the returned text, 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. This method allocates the IGXBuffer object automatically. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
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( )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( )SetFields( ).
- To use a query obtained from another source such as a file, the AppLogic can call getFields( )GetFields( ) and other getXXXX( )GetXXXX( ) member methods to test the query statement before submitting it to the server for processing. The AppLogic can then use the setXXXX( )SetXXXX( ) member methods to change the statement and avoid lengthy queries or syntax errors.
- Use methods in the IGXBuffer 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 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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
// Get the columns specified in the query's SELECT clause
qryFields = Util.toString(qry.getFields());
Related Topics
createQuery( )createQuery( ) in the AppLogic class (deprecated)GXAppLogic class
Returns the GROUP BY clause of the query.
Syntax
public IBuffer getGroupBy()
HRESULT GetGroupBy(
IGXBuffer **ppBuff);
ppBuff. Pointer to the IGXBuffer object that contains the returned text, the GROUP BY clause of the query. This method allocates the IGXBuffer object automatically. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
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( )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( )SetGroupBy( ).
- To use a query obtained from another source such as a file, the AppLogic can call getGroupBy( )GetGroupBy( ) and other getXXXX( )GetXXXX( ) member methods to test the query statement before submitting it to the server for processing. The AppLogic can then use the setXXXX( )SetXXXX( ) member methods to change the statement and avoid lengthy queries or syntax errors.
- Use methods in the IGXBuffer 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 GROUP BY clause of the query, or null for failure.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
// Obtain the GROUP BY clause specified in the query
qryGroup = Util.toString(qry.getGroupBy());
Related Topics
createQuery( )createQuery( ) in the AppLogic class (deprecated)GXAppLogic class
Returns the HAVING clause of the query.
Syntax
public IBuffer getHaving()
HRESULT GetHaving(
IGXBuffer **ppBuff);
ppBuff. Pointer to the IGXBuffer object that contains the returned text, the HAVING clause of the query. This method allocates the IGXBuffer object automatically. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
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( )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( )SetHaving( ).
- To use a query obtained from another source such as a file, the AppLogic can call getHaving( )GetHaving( ) and other getXXXX( )GetXXXX( ) member methods to test the query statement before submitting it to the server for processing. The AppLogic can then use the setXXXX( )SetXXXX( ) member methods to change the statement and avoid lengthy queries or syntax errors.
- Use methods in the IGXBuffer 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 HAVING clause of the query, or null for failure.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
// Obtain the HAVING clause specified in the query
qryHaving = Util.toString(qry.getHaving());
Related Topics
createQuery( )createQuery( ) in the AppLogic class (deprecated)GXAppLogic class
Returns the ORDER BY clause of the query.
Syntax
public IBuffer getOrderBy()
HRESULT GetOrderBy(
IGXBuffer **ppBuff);
ppBuff. Pointer to the IGXBuffer object that contains the returned text, the ORDER BY clause of the query. This method allocates the IGXBuffer object automatically. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
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( )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( )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( )GetOrderBy( ) and other getXXXX( )GetXXXX( ) member methods to test the query statement before submitting it to the server for processing. The AppLogic can then use the setXXXX( )SetXXXX( ) member methods to change the statement and avoid lengthy queries or syntax errors.
- Use methods in the IGXBuffer 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 ORDER BY clause of the query, or null for failure.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
// Obtain the ORDER BY clause specified in the query
qryOrder = Util.toString(qry.getOrderBy());
Related Topics
createQuery( )createQuery( ) in the AppLogic class (deprecated)GXAppLogic class
Returns the SQL pass-through statement associated with the query.
Syntax
public IBuffer getSQL()
HRESULT GetSQL(
IGXBuffer **ppBuff);
ppBuff. Pointer to the IGXBuffer object that contains the returned text, the SQL pass-through statement of the query, in a single concatenated string. This method allocates the IGXBuffer object automatically. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use getSQL( )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( )SetSQL( ).
Rule
If a query is set using setSQL( )SetSQL( ) as well as the setXXXX( )SetXXXX( ) methods, the setSQL( )SetSQL( ) string will be executed, not the string specified by setXXXX( )SetXXXX( ).
- To use a query obtained from another source such as a file, the AppLogic can call getSQL( )GetSQL( ) and other getXXXX( )GetXXXX( ) member methods to test the query statement before submitting it to the server for processing. The AppLogic can then use the setXXXX( )SetXXXX( ) member methods to change the statement and avoid lengthy queries or syntax errors.
- Use methods in the IGXBuffer 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 SQL pass-through statement of the query (as a single concatenated string), or null for failure.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
// Obtain the SELECT statement specified in the query
qrySelect = Util.toString(qry.getSQL());
Related Topics
createQuery( )createQuery( ) in the AppLogic class (deprecated)GXAppLogic class
Returns a comma-separated list of tables in the FROM clause of the query.
Syntax
public IBuffer getTables()
HRESULT GetTables(
IGXBuffer **ppBuff);
ppBuff. Pointer to the IGXBuffer object that contains the returned text, the FROM clause of the query. This method allocates the IGXBuffer object automatically. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
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( )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( )SetTables( ).
- To use a query obtained from another source such as a file, the AppLogic can call getTables( )getTables( ) and other getXXXX( )GetXXXX( ) member methods to test the query statement before submitting it to the server for processing. The AppLogic can then use the setXXXX( )SetXXXX( ) member methods to change the statement and avoid lengthy queries or syntax errors.
- Use methods in the IGXBuffer 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 FROM clause of the query, or null for failure.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
// Obtain the FROM clause specified in the query
qryFrom = Util.toString(qry.getTables());
Related Topics
createQuery( )createQuery( ) in the AppLogic class (deprecated)GXAppLogic class
Returns the WHERE clause of the query.
Syntax
public IBuffer getWhere()
HRESULT GetWhere(
IGXBuffer **ppBuff);
ppBuff. Pointer to the IGXBuffer object that contains the returned text, the WHERE clause of the query. This method allocates the IGXBuffer object automatically. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
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( )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( )SetWhere( ).
- To use a query obtained from another source such as a file, the AppLogic can call getWhere( )GetWhere( ) and other getXXXX( )GetXXXX( ) member methods to test the query statement before submitting it to the server for processing. The AppLogic can then use the setXXXX( )SetXXXX( ) member methods to change the statement and avoid lengthy queries or syntax errors.
- Use methods in the IGXBuffer 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 WHERE clause of the query, or null for failure.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
// Obtains the WHERE clause specified in the query
qryWhere = Util.toString(qry.getWhere());
Related Topics
createQuery( )createQuery( ) in the AppLogic class (deprecated)GXAppLogic class
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)
HRESULT SetFields(
LPSTR 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( )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( )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( )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.
HRESULT, which is set to 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 calculation
qry.setFields("ProdID, ProdPrice * ProdQty AS ExtPrice");
Example 3
// Parentheses specify mathematical operator precedence
qry1.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 result
qry1.setFields("COUNT(invoice.id) as totalSold");
qry2.setFields("SUM(city.population) as urbanPopulation");
pQuery->SetTables("OBCustomer, OBAccount");
pQuery->SetTables("OBCustomer");
pQuery->SetFields("lastName, firstName, userName, ssn");
pQuery->SetWhere(whereClause);
pQuery->SetOrderBy("lastName, firstName");
Related Topics
createQuery( )createQuery( ) in the AppLogic class (deprecated)GXAppLogic class
"Specifying Columns and Computed Fields"
Specifies the GROUP BY clause of the query, determining how rows are grouped and calculated.
Syntax
public int setGroupBy(
String szGroupBy)
HRESULT SetGroupBy(
LPSTR 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.
HRESULT, which is set to 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( )createQuery( ) in the AppLogic class (deprecated)GXAppLogic class
Specifies the HAVING clause of the query, determining which aggregate rows qualify for inclusion in the result set.
Syntax
public int setHaving(
String szGroupBy)
HRESULT SetHaving(
LPSTR 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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
// Set condition on aggregate rows to an
qry.setHaving("AverageAmt > 1000");
Related Topics
createQuery( )createQuery( ) in the AppLogic class (deprecated)GXAppLogic class
Specifies the ORDER BY clause of the query, determining how rows are sorted in the result set.
Syntax
public int setOrderBy(
String szOrderBy)
HRESULT SetOrderBy(
LPSTR 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( )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.
HRESULT, which is set to 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");
pQuery->SetTables("OBCustomer, OBAccount");
pQuery->SetTables("OBCustomer");
pQuery->SetFields("lastName, firstName, userName, ssn");
pQuery->SetWhere(whereClause);
pQuery->SetOrderBy("lastName, firstName");
Related Topics
createQuery( )createQuery( ) in the AppLogic class (deprecated)GXAppLogic class
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( )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( )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( )SetSQL( ) overrides all previous calls to setXXXX( )SetXXXX( ) member methods for this query object. If a query is set using setSQL( )SetSQL( ) as well as the setXXXX( )SetXXXX( ) methods, the setSQL( )SetSQL( ) string will be executed, not the string specified by setXXXX( )SetXXXX( ).
- If the statement is part of a transaction, the AppLogic must first create an instance of the ITrans Interface (deprecated)IGXTrans interface using createTrans( )CreateTrans( ) in the AppLogic class (deprecated)AppLogic class (deprecated). The AppLogic must then call begin( )Begin( ) before executing the statement and, after executing the statement, call commit( )Commit( ) or rollback( )Rollback( ) as appropriate.
Tip
To determine whether a column is defined as NOT NULL, use getNullsAllowed( )GetNullsAllowed( ) in the IColumn Interface (deprecated)IGXColumn interface.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to 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");
// Create a query to update a table
if(((hr=CreateQuery(&pUserQuery))==GXE_SUCCESS)&&pUserQuery) {
pUserQuery->SetSQL("UPDATE OBUser SET password = :password, eMail =
:eMail WHERE userName = :userName");
Related Topics
createQuery( )createQuery( ) in the AppLogic class (deprecated)GXAppLogic class
"Using Pass-Through Database Commands"
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)
HRESULT SetTables(
LPSTR 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.
Return Value
SetWhere( )
Example 1
// Specify invoice, customer, invoice, and catalog tables
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");
Example 2
// Specify same table, using as keyword, for different users
qry.setTables("customer, customer as cust2")
pQuery->SetTables("OBCustomer, OBAccount");
pQuery->SetTables("OBCustomer");
pQuery->SetFields("lastName, firstName, userName, ssn");
pQuery->SetWhere(whereClause);
pQuery->SetOrderBy("lastName, firstName");
Related Topics
createQuery( )createQuery( ) in the AppLogic class (deprecated)GXAppLogic class
Specifies the WHERE clause of the query, determining which rows qualify for inclusion in the result set.
Syntax
public int setWhere(
String szWhere)
HRESULT SetWhere(
LPSTR 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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example 1
// Obtain user info from the user database
qry.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 queries
qry1.setWhere("urbanPopulation >= 1000000");
qry2.setWhere("region = 'West' or region = 'East'");
pQuery->SetTables("OBCustomer, OBAccount");
pQuery->SetTables("OBCustomer");
pQuery->SetFields("lastName, firstName, userName, ssn");
pQuery->SetWhere(whereClause);
pQuery->SetOrderBy("lastName, firstName");
Related Topics
createQuery( )createQuery( ) in the AppLogic class (deprecated)GXAppLogic class
"Specifying Conditions on Row Retrieval"
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 IGXResultSet interface represents the results of a flat query. IResultSet IGXResultSet 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( )GetValueString( ). If retrieving binary data, use getValueBinary( )GetValueBinary( ).
To process hierarchical result sets, use methods in the IHierResultSet Interface (deprecated)IGXHierResultSet interface or evalTemplate( )EvalTemplate( ) in the AppLogic class (deprecated)GXAppLogic class instead.
IResultSet IGXResultSet is part of the Data Access Engine (DAE) service.
To create an instance of the IResultSet IGXResultSet interface, use executeQuery( )ExecuteQuery( ) in the IDataConn Interface (deprecated)IGXDataConn interface or execute( )Execute( ) in the IPreparedQuery Interface (deprecated)IGXPreparedQuery interface., as shown in the following example:
rs = conn.executeQuery(0, qry, null, null);
Package Include File
com.kivasoftgxidata.h
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( )ExecuteQuery( ) in the IDataConn Interface (deprecated)IGXDataConn interface
execute( )Execute( ) in the IPreparedQuery Interface (deprecated)IGXPreparedQuery interface
"Getting Data From a Flat Query's Result Set"
Releases the connection used by the result set.
Syntax
public int close(
int dwFlags)
HRESULT FetchNext(
DWORD dwFlags);
dwFlags. Specify 0 (zero). Internal use only.
Usage
Call close( )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( )Close( ), release the result set object by calling theits GX.Release( )Release( ) method.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to 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( )EnumColumnReset( ) before iterating through and retrieving columns in a result set. The enumColumnReset( )EnumColumnReset( ) method ensures that column retrieval starts from the first column.
Thereafter, use enumColumns( )EnumColumns( ) to retrieve each column sequentially. Each enumColumns( )EnumColumns( ) call returns an IColumnIGXColumn object for the next column.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to 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 = ";
Related Topics
"Getting Data From a Flat Query's Result Set"
Returns the definition of the next column in the result set.
Syntax
public IColumn enumColumns()
HRESULT EnumColumns(
IGXColumn **ppColumn);
ppColumn. Pointer to the IGXColumn object that contains the returned column of data. When the client code is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use enumColumns( )EnumColumns( ) when the column definition is unknown and required for subsequent operations. The AppLogic can use the returned IColumnIGXColumn 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( )EnumColumnReset( ) to ensure that enumColumns( )EnumColumns( ) starts with the first column in the table. Each subsequent enumColumns( )EnumColumns( ) call moves to the next sequential column in the result set and retrieves its column definition in an IColumnIGXColumn object.
- The columns might not be returned in the order in which they are defined in the database catalog.
- Test for nullNULL 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).
HRESULT, which is set to 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 = ";
Related Topics
IColumn Interface (deprecated)IGXColumn interface
"Getting Data From a Flat Query's Result Set"
Retrieves the next row in the result set.
Usage
Use fetchNext( )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( )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( )ExecuteQuery( ) in the IDataConn Interface (deprecated)IGXDataConn interface.
- 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( )MoveTo( ) and specifying row number 1. This works only when buffering is enabled.
- If result set buffering is enabled, the AppLogic can use moveTo( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
- If the end of the result set has been reached, HRESULT is set to GX_DA_END_OF_FETCH, a macro-based constant (defined in gxidata.h).
- If the length of the buffer has been exceeded, HRESULT is set to GX_DA_BUFFER_EXCEEDED, a macro-based constant (defined in gxidata.h).
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( )ExecuteQuery( ) in the IDataConn Interface (deprecated)IGXDataConn interface
execute( )Execute( ) in the IPreparedQuery Interface (deprecated)IGXPreparedQuery interface
"Getting Data From a Flat Query's Result Set"
Returns the column definition of the column with the specified name.
Syntax
public IColumn getColumn(
String colName)
HRESULT GetColumn(
LPSTR colName,
IGXColumn **ppCol);
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.
ppCol. Pointer to the IGXColumn object that contains the returned column definition. Calling GetColumn( ) creates the IGXColumn object automatically. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use getColumn( )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)IGXColumn interface 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( )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( )SetFields( ) in the IQuery Interface (deprecated)IGXQuery interface to specify field aliases.
Return Value
IColumn object, or null for failure (such as an invalid column name).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
// Determine whether the column name is valid
if((col=rs.getColumn("CustID"))==null)
// otherwise, process column using IColumn methods ...
Related Topics
IColumn Interface (deprecated)IGXColumn interface
executeQuery( )ExecuteQuery( ) in the IDataConn Interface (deprecated)IGXDataConn interface
execute( )Execute( ) in the IPreparedQuery Interface (deprecated)IGXPreparedQuery interface
"Getting Data From a Flat Query's Result Set"
Returns the column definition for the column in the specified ordinal position.
Syntax
public IColumn getColumnByOrd(
int colIndex)
HRESULT GetColumnByOrd(
ULONG colIndex,
IGXColumn **ppCol);
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.
ppCol. Pointer to the IGXColumn object that contains the returned column definition. Calling GetColumnByOrd( ) creates the IGXColumn object automatically. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use getColumnByOrd( )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)IGXColumn interface 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( )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).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
// Determine whether the column position is valid
if((col=rs.getColumnByOrd(colOrd))==null)
// otherwise, process column using IColumn methods . . .
Related Topics
IColumn Interface (deprecated)IGXColumn interface
executeQuery( )ExecuteQuery( ) in the IDataConn Interface (deprecated)IGXDataConn interface
execute( )Execute( ) in the IPreparedQuery Interface (deprecated)IGXPreparedQuery interface
"Getting Data From a Flat Query's Result Set"
Returns the ordinal position of the column with the specified name.
Syntax
public int getColumnOrdinal(
String szColumn)
HRESULT GetColumnOrdinal(
LPSTR szColumn,
ULONG *pOrdinal);
szColumn. Name of a column in the result set.
pOrdinal. Pointer to the variable that contains the returned ordinal position of the specified column. The ordinal position of the first column in the result set is 1, the second column is 2, and so on.
Usage
Use getColumnOrdinal( )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**( )GetValue**( ) methods, such as getValueString( )GetValueString( ) and getValueInt( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
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");
IGXHierResultSet *pHRset=NULL;
// Execute a hierarchical query
if(((hr=pHq->Execute(0, 0, NULL, &pHRset))== GXE_SUCCESS)&&pHRset) {
// Get a result set from the hierarchical result set
if(((hr=pHRset->GetResultSet("SelCust", &pRset))== GXE_SUCCESS)&&pRset) {
// Retrieve a value from the result set
// First, get the ordinal position of the column
pRset->GetColumnOrdinal("ssn", &ssnIndex);
// Next, get the value of the specified column
pRset->GetValueString(ssnIndex, tmpStr, 200);
Related Topics
executeQuery( )ExecuteQuery( ) in the IDataConn Interface (deprecated)IGXDataConn interface
execute( )Execute( ) in the IPreparedQuery Interface (deprecated)IGXPreparedQuery interface
"Getting Data From a Flat Query's Result Set"
Returns the number of columns in the result set.
Syntax
public int getNumColumns()
HRESULT GetNumColumns(
ULONG *pnCols);
pnCols. Pointer to the variable that contains the returned number of columns in the result set.
Usage
Use getNumColumns( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
executeQuery( )ExecuteQuery( ) in the IDataConn Interface (deprecated)IGXDataConn interface
"Getting Data From a Flat Query's Result Set"
For asynchronous queries, returns an IOrderIGXOrder object used for obtaining the current status and return value of the query.
Syntax
public IOrder getOrder()
HRESULT GetOrder(
IGXOrder **ppOrder);
ppOrder. Pointer to the IGXOrder object that contains the returned IGXOrder object. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use getOrder( )GetOrder( ) to create an IOrderIGXOrder 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_ASYNCGX_DA_EXEC_ASYNC as the dwFlags parameter in executeQuery( )ExecuteQuery( ) in the IDataConn Interface (deprecated)IGXDataConn interface.
- The AppLogic can determine the status of the query (active, done, cancelled, or unknown) using getState( )GetState( ) in the IOrder Interface (deprecated)IGXOrder interface.
- Alternatively, use WaitForOrder( )in theGX class (deprecated)the GXWaitForOrder( ) function, 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).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
IOrder Interface (deprecated)IGXOrder interface
executeQuery( )ExecuteQuery( ) in the IDataConn Interface (deprecated)IGXDataConn interface
"Getting Data From a Flat Query's Result Set"
Returns the number of the current row in the result set.
Syntax
public int getRowNumber()
HRESULT GetRowNumber(
ULONG *pOrd);
pOrd. Pointer to the variable that contains the returned row number. 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.
Usage
When iterating through rows in the result set, use getRowNumber( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
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( )ExecuteQuery( ) in the IDataConn Interface (deprecated)IGXDataConn interface
execute( )Execute( ) in the IPreparedQuery Interface (deprecated)IGXPreparedQuery interface
"Getting Data From a Flat Query's Result Set"
Returns the processing status of the asynchronous database operation on the database server.
HRESULT GetStatus(
DWORD *pStatus);
pStatus. Pointer to the variable that contains the returned status code. The variable is set to one of the following macro-based constants (defined in gxiorder.h):
Usage
Use getStatus( )GetStatus( ) to return status information to use in error-handling code.
Return Value
One of the following:
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
"Getting Data From a Flat Query's Result Set"
Returns the value of a BINARY column in the current row of the result set.
Syntax
public byte[] getValueBinary(
int Ordinal)
HRESULT GetValueBinary(
ULONG Ordinal,
LPBYTE pValue,
ULONG nSize);
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. Pointer to the buffer that contains the returned column value.
nSize. Size of the buffer to contain the returned column value.
Usage
Use getValueBinary( )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( )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( )GetValueBinaryPiece( ).
Return Value
A byte array for success, or null for failure (such as an invalid column number or data type mismatch).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
"Getting Data From a Flat Query's Result Set"
Returns the value of a LONGBINARY column in the current row from the result set.
Syntax
public byte[] getValueBinaryPiece(
int Ordinal,
int nLength)
HRESULT GetValueBinaryPiece(
ULONG Ordinal,
ULONG nLength,
LPBYTE pValue,
ULONG nSize);
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.
pValue. Pointer to the buffer that contains the returned column value.
nSize. Size of the client-allocated buffer to contain the returned column value.
Usage
Use getValueBinaryPiece( )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( )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( )GetValueBinaryPiece( ) for a row after you call fetchNext( )FetchNext( ).
Tips
- To determine the total size of the binary data that has been retrieved, use getValueSize( )GetValueSize( ).
- To retrieve binary data of which the total size is less than 64Kb, use getValueBinary( )GetValueBinary( ).
Return Value
A byte array for success, or null for failure (such as an invalid column number or data type mismatch).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
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," +
pQuery->SetTables("blobtable");
hr = pConn->ExecuteQuery(0, pQuery, NULL, NULL, &pRS);
if (hr == GXE_SUCCESS && pRS != NULL)
hr = pRS->GetRowNumber(&nRows);
if (hr == GXE_SUCCESS && nRows)
pBlobChunk = new LPBYTE[65536];
hr = pRS->GetValueBinaryPiece(1, expectSize, &pBlobChunk, 65536);
pRS->GetValueSize(1, &gotSize);
fprintf(stderr, "got a full chunk, size = %d\n",
fprintf(stderr, "got a partial chunk, size = %d\n",
Related Topics
"Getting Data From a Flat Query's Result Set"
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)
HRESULT GetValueDateString(
ULONG colIndex,
LPSTR pVal,
ULONG nVal);
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.
pVal. Pointer to the variable that contains the returned column value.
Usage
Use getValueDateString( )GetValueDateString( ) to retrieve date values from the result set for subsequent processing. The following is an example of the format in which getValueDateString( )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).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
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));
Related Topics
"Getting Data From a Flat Query's Result Set"
Returns the value of a double type column from the current row in the result set.
Syntax
public double getValueDouble(
int colIndex)
HRESULT GetValueDouble(
ULONG colIndex,
double *pVal);
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.
pVal. Pointer to the variable that contains the returned column value.
Usage
Use getValueDouble( )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).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
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);
Related Topics
"Getting Data From a Flat Query's Result Set"
Returns the value of an int type column from the current row in the result set.
Syntax
public int getValueInt(
int colIndex)
HRESULT GetValueInt(
ULONG colIndex,
ULONG *pVal);
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.
pVal. Pointer to the variable that contains the returned column value.
Usage
Use getValueInt( )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).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
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);
Related Topics
"Getting Data From a Flat Query's Result Set"
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);
HRESULT GetValueSize(
ULONG colIndex,
ULONG *pSize);
colIndex. Ordinal number (position) of the column in the table definition. The first column is 1, the second column is 2, and so on.
pSize. Pointer to the buffer that contains the returned number of bytes that have been fetched.
Usage
Use getValueSize( )GetValueSize( ) during data retrieval to check the size of the BLOB column that has been retrieved. When the AppLogic first calls getValueSize( )GetValueSize( ) before calling getValueBinaryPiece( )GetValueBinaryPiece( ) to retrieve the value of a LONGBINARY column, getValueSize( )GetValueSize( ) returns 0.
Each subsequent getValueSize( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
getValueBinaryPiece( )GetValueBinaryPiece( )
"Getting Data From a Flat Query's Result Set"
Returns the value of a String type column from the current row in the result set.
Syntax
public String getValueString(
int colIndex)
HRESULT GetValueString(
ULONG colIndex,
LPSTR pVal,
ULONG nVal);
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.
pVal. Pointer to the variable that contains the returned column value.
Usage
Use getValueString( )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).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
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);
IGXHierResultSet *pHRset=NULL;
// Execute a hierarchical query
if(((hr=pHq->Execute(0, 0, NULL, &pHRset))== GXE_SUCCESS)&&pHRset) {
// Get a result set from the hierarchical result set
if(((hr=pHRset->GetResultSet("SelCust", &pRset))== GXE_SUCCESS)&&pRset) {
// Retrieve a value from the result set
// First, get the ordinal position of the column
pRset->GetColumnOrdinal("ssn", &ssnIndex);
// Next, get the value of the specified column
pRset->GetValueString(ssnIndex, tmpStr, 200);
Related Topics
"Getting Data From a Flat Query's Result Set"
Returns the value of a TEXT column in the current row from the result set.
Syntax
public String getValueText(
int Ordinal)
HRESULT GetValueText(
ULONG Ordinal,
LPSTR pValue,
ULONG nSize);
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. Pointer to the buffer that contains the returned column value.
nSize. Size of the client-allocated buffer to contain the returned column value.
Usage
Use getValueText( )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( )GetValueSize( ).
- If the value of the data is of type LONGTEXT, use getValueTextPiece( )GetValueTextPiece( ).
Return Value
A String object, or null for failure (such as an invalid column number or data type mismatch).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
"Getting Data From a Flat Query's Result Set"
Returns the value of a LONGTEXT column in the current row from the result set.
Syntax
public String getValueTextPiece(
int Ordinal,
int nLength)
HRESULT GetValueTextPiece(
ULONG Ordinal,
ULONG nLength,
LPSTR pValue,
ULONG nSize);
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.
pValue. Pointer to the buffer that contains the returned column value.
nSize. Size of the client-allocated buffer to contain the returned column value.
Usage
Use getValueTextPiece( )GetValueTextPiece( ) to retrieve LONGTEXT data. LONGTEXT values must be retrieved in 64K increments, therefore, you must use getValueTextPiece( )GetValueTextPiece( ) repeatedly to retrieve the data.
- The data type of the column must be LONGTEXT or database equivalent.
- Call getValueTextPiece( )GetValueTextPiece( ) until you get all the data before calling fetchNext( )FetchNext( ) again.
Tips
- To determine the actual size of the LONGTEXT data, use getValueSize( )GetValueSize( ). The actual size of the data determines the number of times you need to call getValueTextPiece( )GetValueTextPiece( ).
- For data of type TEXT, use getValueText( )GetValueText( ).
Return Value
A String object, or null for failure (such as an invalid column number or data type mismatch).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
"Getting Data From a Flat Query's Result Set"
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( )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( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds. If the end of the result set has been reached, HRESULT is set to GXE_EOF.
Related Topics
executeQuery( )ExecuteQuery( ) in the IDataConn Interface (deprecated)IGXDataConn interface
execute( )Execute( ) in the IPreparedQuery Interface (deprecated)IGXPreparedQuery interface
"Getting Data From a Flat Query's Result Set"
Returns the total number of rows retrieved thus far from the data source.
HRESULT RowCount(
ULONG *nRows);
nRows. Pointer to the variable that contains the returned number of rows in the result set.
Usage
Use rowCount( )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( )RowCount( ) to determine the current maximum number of rows to process.
Tip
If result set buffering is enabled, the AppLogic can use rowCount( )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).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
htmlString += rs.getValueString(DESCRIPTION_COL);
// Truncate the report after 10 rows.
} while (rs.fetchNext() == GXE_SUCCESS);
if(((hr=pConn->ExecuteQuery(0, pQuery, NULL, NULL, &pRset))==GXE_SUCCESS)&&pRset) {
// Check if there is data in the result set
if(((hr=pRset->RowCount(&numRows))==GXE_SUCCESS)&&numRows)
Related Topics
executeQuery( )ExecuteQuery( ) in the IDataConn Interface (deprecated)IGXDataConn interface
execute( )Execute( ) in the IPreparedQuery Interface (deprecated)IGXPreparedQuery interface
"Getting Data From a Flat Query's Result Set"
Checks if the value of a column is null or not.
Syntax
public boolean wasNull(
int Ordinal)
HRESULT WasNull(
ULONG Ordinal,
BOOL *bNull);
Ordinal. Ordinal number (position) of the column in the table definition. The first column is 1, the second column is 2, and so on.
bNull. Pointer to the client-allocated BOOL variable that contains the returned information.
Usage
Use wasNull( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
"Getting Data From a Flat Query's Result Set"
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 SQLException
metaData. 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 IGXSequence 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 IGXSequence 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 IGXSequence interface is part of the Data Access Engine (DAE) service.
To create an instance of the ISequence interface IGXSequence interface, use createSequence( )CreateSequence( ) in the ISequenceMgr Interface (deprecated)IGXSequenceMgr interface, as shown in the following example:
hr = CreateDataConn(0, GX_DA_DRIVER_ODBC, conn_params, NULL, &conn);
//Cast the connection to the ISequenceMgr interface
hr = conn->QueryInterface(IID_IGXSequenceMgr, (LPVOID *)
hr = seqmgr->CreateSequence("mySeq", "orders.ID", 100,
Package Include File
com.kivasoft gxisequence.h
Related Topics
createSequence( )CreateSequence( ) in the ISequenceMgr Interface (deprecated)IGXSequenceMgr interface
Deletes the sequence from the database.
Usage
Use drop( )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( )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( )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( )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
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
createSequence( )CreateSequence( ) in the ISequenceMgr Interface (deprecated)IGXSequenceMgr interface
Returns the current value in the sequence.
Syntax
public int getCurrent();
HRESULT GetCurrent(
DWORD *dwCurrVal);
dwCurrVal. Pointer to the variable that contains the returned current value of the sequence.
Usage
Use getCurrent( )GetCurrent( ) to obtain the current value of the sequence without actually incrementing the sequence value.
Alternatively, use getNext( )GetNext( ) to increment the sequence and obtain its incremented value.
Rule
For Oracle databases, the session must first call getNext( )GetNext( ) before it can call getCurrent( )GetCurrent( ).
Tip
UnlikegetNext( ) GetNext( ), calling getCurrent( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
createSequence( )CreateSequence( ) in the ISequenceMgr Interface (deprecated)IGXSequenceMgr interface
Increments the sequence and returns its incremented value.
HRESULT GetNext(
DWORD *dwCurrVal);
dwCurrVal. Pointer to the variable that contains the returned incremented value of the sequence.
Usage
Use getNext( )GetNext( ) to increment and return the value of the sequence by the amount specified in the incrementdwIncrement parameter in the createSequence( )CreateSequence( ) method in the ISequenceMgr Interface (deprecated)IGXSequenceMgr interface. The incrementation value is always a positive integer.
Alternatively, use getCurrent( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
- For Informix and Sybase databases, the session that creates the sequence must call getNext( )GetNext( ) at least once before any other session can call getSequence( )GetSequence( ) in the ISequenceMgr Interface (deprecated)IGXSequenceMgr interface.
- For Oracle databases, the session must first call getNext( )GetNext( ) before it can call getCurrent( )GetCurrent( ).
Tip
Successive calls to getNext( )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 +")");
hr = CreateDataConn(0, GX_DA_DRIVER_ODBC, conn_params, NULL, &conn);
// Cast the connection to an ISequenceMgr interface
hr = conn->QueryInterface(IID_IGXSequenceMgr, (LPVOID *)
hr = seqmgr->CreateSequence("mySeq", "orders.ID", 100,
// To start the sequence, call GetNext()
sprintf(tmp, "INSERT into orders (ID) values
(%d), (cust) values (%s)", seqVal,
// ... Execute insert command.
Related Topics
createSequence( )CreateSequence( ) in the ISequenceMgr Interface (deprecated)IGXSequenceMgr interface
ISequenceMgr Interface (deprecated)
ISequenceMgr is deprecated and is provided for backward compatibility only.
The ISequenceMgrIGXSequenceMgr interface provides methods for creating and retrieving an ISequence IGXSequence 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( )CreateSequence( ), the AppLogic can use methods in the ISequence Interface (deprecated)IGXSequence interface to retrieve sequence values.
The ISequenceMgrIGXSequenceMgr interface is part of the Data Access Engine (DAE) service.
The ISequenceMgrIGXSequenceMgr interface is implemented by the IDataConnIGXDataConn object. To use it, cast IDataConnIGXDataConn to the ISequenceMgrIGXSequenceMgr interface, as shown in the following example:
dc->QueryInterface(IID_IGXSequenceMgr, (LPVOID *) &sm);
Package Include File
com.kivasoft gxisequence.h
Method
Description
Returns an existing sequence object for the specified sequence name in the underlying database.
Related Topics
ISequence Interface (deprecated)IGXSequence interface
Creates a new sequence object in the underlying database.
Syntax
public ISequence createSequence(
String szName,
String szCol,
int dwStart,
int dwIncrement,
String szOptions);
HRESULT CreateSequence(
LPSTR szName,
LPSTR szCol,
DWORD dwStart,
DWORD dwIncrement,
LPSTR szOptions,
IGXSequence **ppSequence);
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 nullNULL, 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( )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 SQL Server (Sybase and Microsoft) databases, these are column options for the "CREATE Table"command.
- For Informix, no options exist.
For more information, see your database vendor's documentation.
ppSequence. Pointer to the returned IGXSequence object. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use createSequence( )CreateSequence( ) to create a new ISequenceIGXSequence object, representing an incremental number generator, with the specified starting value. The AppLogic can then use methods in the ISequence Interface (deprecated)IGXSequence interface 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( )CreateSequence( ) creates a sequence object. For Sybase, Informix, and Microsoft SQL Server databases, createSequence( )CreateSequence( ) creates a table object with a sequence column.
Return Value
ISequence object, or null for failure (such as an invalid database connection).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
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 +")");
hr = CreateDataConn(0, GX_DA_DRIVER_ODBC, conn_params, NULL, &conn);
// Cast the connection to an ISequenceMgr interface
hr = conn->QueryInterface(IID_IGXSequenceMgr, (LPVOID *)
hr = seqmgr->CreateSequence("mySeq", "orders.ID", 100,
// To start the sequence, call GetNext()
sprintf(tmp, "INSERT into orders (ID) values
(%d), (cust) values (%s)", seqVal,
// ... Execute insert command.
Related Topics
ISequence Interface (deprecated)IGXSequence interface
Returns an existing sequence object, for the specified sequence name, from the underlying database.
dc->QueryInterface(IID_IGXSequenceMgr, (LPVOID *) &sm);
HRESULT GetSequence(
LPSTR szName,
LPSTR szCol,
IGXSequence **ppSequence);
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 nullNULL, defaults to "SEQVAL".
ppSequence. Pointer to the returned IGXSequence object. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use getSequence( )GetSequence( ) to obtain the ISequenceIGXSequence object with the specified name in the underlying database. The AppLogic can then use methods in the ISequence Interface (deprecated)IGXSequence interface 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( )CreateSequence( ) to create the ISequenceIGXSequence object.
- The specified sequence name must be valid.
- For Informix and Sybase databases, the session that creates the sequence must call getNext( )GetNext( ) at least once before any other session can call getSequence( )GetSequence( ).
Return Value
ISequence object, or null for failure (such as an invalid sequence name).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
ISequence Interface (deprecated)IGXSequence interfaceiAS
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.
- 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.
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( ).
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.
- Use the default handling, but change the template to be streamed.
- Handle the error completely by yourself.
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( ).
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, ServletException
request. 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 ISession2IGXSession2 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.
- 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( )DestroySession( ) method in the AppLogicGXAppLogic class.
- Scope. You can specify if the session data is available at the local, cluster, or enterprise-wide level.
The ISession2IGXSession2 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.
To create an instance of the ISession2IGXSession2 interface, use the createSession( )CreateSession( ) method in the AppLogicGXAppLogic class.
If your application requires a custom session object, for example, to support additional methods, you can subclass the Session2 class (deprecated)GXSession2 class and define your own methods.
Package Include File
com.kivasoft gxapplogic.h
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()
HRESULT GetSessionApp(
LPSTR pAppName
ULONG nAppName);
pAppName. Pointer to the buffer allocated by the client to store the returned application name.
nAppName. The size of the buffer to store the application name.
Usage
Use getSessionApp( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
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);
//Create a session and associate it with myApp application
hr = CreateSession(GXSESSION_DISTRIB, 0, "myApp",
//Get the application name associated with the session
//GetSessionApp() should return "myApp"
hr = m_pSession->GetSessionApp(AppName, 128);
return Result("GetSessionApp returned error");
sprintf(msg, "Session application name:%s\n\n", AppName);
Related Topics
createSession( )CreateSession( ) in the AppLogicGXAppLogic class
Syntax
public IValList getSessionData()
HRESULT GetSessionData(
IGXValList **ppSessionData);
ppSessionData. Pointer to the IGXValList object that contains the returned session data. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use getSessionData( )GetSessionData( ) to retrieve session data for processing. Data is returned in an IValListIGXValList object. This method retrieves the contents that were last saved in the distributed store with saveSession( )SaveSession( ). Use methods in the IValListIGXValList interface to iterate through and access items in the IValListIGXValList object.
Return Value
IValList object containing the session information, or null for failure.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
public class OBSession extends Object
protected 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");
// Method for retrieving the user name from session data
// Pull the username from the session data
if((GetSessionData(&pData)==GXE_SUCCESS)&&pData) {
LPSTR pTmp=GXGetValListString(pData, "userName");
pRet=new char[strlen(pTmp)+1];
Related Topics
createSession( )CreateSession( ) in the AppLogicGXAppLogic class
Returns the flags associated with the session when it was created.
Syntax
public int getSessionFlags()
HRESULT GetSessionFlags(
DWORD *pdwFlags);
pdwFlags. Pointer to the client-allocated variable that contains the returned session flag.
Usage
Use getSessionFlags( )GetSessionFlags( ) to retrieve the flags that were specified when the session was created with createSession( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
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();
//Create a session with distributed scope
hr = CreateSession(GXSESSION_DISTRIB, 0, "myApp",
//Get the flag associated with the session
//GetSessionFlags() should return GXSESSION_DISTRIB
hr = m_pSession->GetSessionFlags(&Flag);
return Result("GetSessionFlags returned error");
sprintf(msg, "Session flag:0x%x\n", Flag);
Related Topics
createSession( )CreateSession( ) in the AppLogicGXAppLogic class
Syntax
public String getSessionID()
HRESULT GetSessionID(
LPCSTR pSessID
ULONG nSessID);
pSessID. Pointer to the buffer allocated by the client to store the returned session ID.
nSessID. The size of the buffer to store the session ID.
Usage
Use getSessionID( )GetSessionID( ) to retrieve the unique ID associated with a session. The GetSessionID( ) method returns the base or intrinsic ID, not the transformed IDs generated by a custom ID generator.
Return Value
A string representing the session ID, or null for failure.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
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");
//Create a session using the default ID generator
hr = CreateSession(GXSESSION_DISTRIB, 0, "myApp",
hr = m_pSession->GetSessionID(SessID, 128);
return Result("GetSessionID returned error");
sprintf(msg, "Session ID:%s\n", SessID);
Related Topics
createSession( )CreateSession( ) in the AppLogicGXAppLogic class
Returns the session's timeout value in seconds.
Syntax
public int getSessionTimeout()
HRESULT GetSessionData(
ULONG *pTimeout);
pTimeout. Pointer to the buffer allocated by the client to store the returned timeout value.
Usage
Use getSessionTimeout( )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( )DestroySession( ) method.
Return Value
Integer representing the timeout value in seconds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
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);
//Create a session with no timeout value
hr = CreateSession(GXSESSION_DISTRIB, 0, "myApp",
//getSessionTimeout() should return 0
hr = m_pSession->GetSessionTimeout(&Timeout);
return Result("GetSessionTimeout returned error");
sprintf(msg, "Session timeout value:%d\n", Timeout);
Related Topics
createSession( )CreateSession( ) in the AppLogicGXAppLogic class
Syntax
public int saveSession(
int dwFlags)
HRESULT saveSession(
DWORD dwFlags);
Usage
Use saveSession( )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( )SaveSession( ) method in the AppLogicGXAppLogic class at least once to set a cookie, which passes the session ID between the Web browser and iPlanet Application Server. The saveSession( )SaveSession( ) method in the ISession2IGXSession2 interface only saves data to the distributed state store, whereas saveSession( )SaveSession( ) in the AppLogicGXAppLogic class saves data to the distributed state store and sets a cookie.
- The AppLogic should call saveSession( )SaveSession( ) to save changes after updating session data with setSessionData( )SetSessionData( ) or after modifying the IValListIGXValList returned by getSessionData( )GetSessionData( ).
- To improve performance, keep smaller amounts of information in the session.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
createSession( )CreateSession( ) and saveSession( )SaveSession( ) in the AppLogicGXAppLogic class
Updates session with specified data.
Syntax
public int setSessionData(
IValList pSessionData)
HRESULT SetSessionData(
IGXValList *pSessionData);
pSessionData. The IValListIGXValList object containing the session data to set.
Usage
Use setSessionData( )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( )SaveSession( ) to save changes after updating session data with setSessionData( )SetSessionData( ).
- To improve performance, keep smaller amounts of information in the session.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
createSession( )CreateSession( ) in the AppLogicGXAppLogic 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 ISessionIDGenIGXSessionIDGen interface represents a session ID generator. The session-related methods in the AppLogicGXAppLogic class take an ISessionIDGenIGXSessionIDGen object as a parameter. By default, iPlanet Application Server uses the ISessionIDGenIGXSessionIDGen object to generate a session ID when an AppLogic creates a new session with the createSession( )CreateSession( ) method in the AppLogicGXAppLogic 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.
If you want to use your own technique for generating session IDs, you can create a class that implements the IGXSessionIDGen interface and add your own code.
If your application requires additional security, you can implement a custom session ID generator that continually changes the session ID that is passed between the Web browser and iPlanet Application Server. Internally, however, there must be a constant or base ID that remains unchanged for the iPlanet Application Server to identify sessions correctly. Therefore, your custom code needs to implement an algorithm for creating and mapping variable IDs to a base ID.
The IGXSessionIDGen interface defines methods for generating session IDs, creating variable IDs, and mapping variable IDs to the base ID. To implement a custom session ID generator, create a class that implements the IGXSessionIDGen interface, and implement all the interface methods.
Package Include File
com.kivasoftgxapplogic.h
Related Topics
createSession( )CreateSession( ) and getSession( )GetSession( ) in the AppLogic class (deprecated)GXAppLogic class
ISession2 Interface (deprecated)IGXSession2 interface
Syntax
HRESULT GenerateSessID(
DWORD dwFlags,
ULONG nSessID,
LPSTR pSessID);
dwFlags. Specify 0. For internal use only.
nSessID. The size of the buffer to store the returned session ID.
pSessID. The buffer to store the returned session ID.
Usage
When an AppLogic calls CreateSession( ) to create a new session, it needs to pass in a pointer to an IGXSessionIDGen object as an argument. If the AppLogic passes NULL, the iPlanet Application Server uses the default IGXSessionIDGen to generate a session ID.
To use a different mechanism for generating session IDs, create a class that implements the IGXSessionIDGen interface and implement GenerateSessID( ). When you pass your session ID generator object as an argument to CreateSession( ), it invokes your implementation of GenerateSessID( ).
Return Value
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
In the following code example, which is specific to the Solaris platform, GenerateSessID( ) is implemented to use a high resolution counter as the session ID:
MySessIDGen::GenerateSessID(DWORD dwFlags, ULONG nSessID, LPSTR pSessID)
sprintf(id, "%lld", HiResCounter);
strncpy(pSessID, id, nSessID);
Related Topics
GenerateVariantID( ), MapToBaseID( )
Accepts an input session ID and generates a different ID.
Syntax
HRESULT GenerateVariantID(
LPCSTR pBaseID,
DWORD dwFlags,
ULONG nVariantID
LPSTR pVariantID);
pBaseID. The base session ID from which the variable ID is to be generated.
dwFlags. Specify 0 (zero). For internal use only.
nVariantID. The size of the buffer to store the variable session ID.
pSessID. The buffer to store the variable session ID.
Usage
If your AppLogic creates a custom class to implement the IGXSessionIDGen interface, you need to implement all the methods in the interface, including GenerateVariantID( ).
You can write GenerateVariantID( ) to implement a way to generate session IDs that change. Changing a session's ID as it is passed between the Web browser and iPlanet Application Server provides additional security. Internally, however, the iPlanet Application Server uses a base ID that does not change. Therefore, if you implement GenerateVariantID( ) to create variable IDs, you also need to write MaptoBaseID( ) to convert variable IDs to a base ID.
If you don't want to generate variable IDs in your application, implement GenerateVariantID( ) to simply return the base ID.
Return Value
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
In the following code example, which is specific to the Solaris platform, GenerateVariantID( ) is implemented to generate different IDs from a base ID:
MySessIDGen::GenerateVariantID(LPCSTR pBaseID, DWORD dwFlags,ULONG nVariantID, LPSTR pVariantID)
if (!pBaseID || !pVariantID || nVariantID <= GXStrLen(pBaseID))
sprintf(id, "%lld.%s", HiResCounter, pBaseID);
strncpy(pVariantID, id, nVariantID);
pVariantID[nVariantID-1] = '\0';
Related Topics
GenerateSessID( ), MapToBaseID( )
Maps a variable session ID to a base ID.
Syntax
HRESULT MapToBaseID(
LPCSTR pVariantID,
DWORD dwFlags,
ULONG nBaseID,
LPSTR pBaseID);
pVariantID. The variable ID to map to the base ID.
dwFlags. Specify 0 (zero). For internal use only.
nBaseID. The size of the buffer to store the returned base ID.
pBaseID. The buffer to store the returned base ID.
Usage
If your AppLogic creates a custom class to implement the IGXSessionIDGen interface, you need to implement all the methods in the interface, including MapToBaseID( ).
You can write MapToBaseID( ) in conjunction with GenerateVariantID( ) to implement a way to generate session IDs that change. Changing a session's ID as it is passed between the Web browser and iPlanet Application Server provides additional security. Internally, however, the iPlanet Application Server uses a base ID that does not change. Therefore, if you implement GenerateVariantID( ) to create variable IDs, you also need to implement MaptoBaseID( ) to convert these variable IDs to a base ID.
If you don't want to generate variable IDs in your application, implement GenerateVariantID( ) and MapToBaseID( ) to simply return the base ID.
Return Value
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
In the following code example, MapToBaseID( ) is overridden to convert variable IDs generated by GenerateVariantID( ) to the base ID:
MySessIDGen::MapToBaseID(LPCSTR pVariantID, DWORD dwFlags, ULONG nBaseID, LPSTR pBaseID)
LPSTR p = strchr(pVariantID, '.');
strncpy(pBaseID, id, nBaseID);
Related Topics
GenerateVariantID( ), GenerateSessID( )
The IState2IGXState2 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.
- Contents in the form of an IValListIGXValList.
- 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.
The IState2IGXState2 interface defines methods for creating and deleting nodes, setting and retrieving node contents, and retrieving the attributes of a node.
To create a state tree, use the following methods:
- getStateTreeRoot( )GetStateTreeRoot( ) method in the AppLogicGXAppLogic class to create the root node.
- createStateChild( )CreateStateChild( ) in this interface to create the child nodes.
Package Include File
com.kivasoft gxistate.h
Method
Description
Creates a child node under the node on which this method is called.
deleteStateChild( )DeleteStateChild( )
getStateChild( )GetStateChild( )
getStateChildCount( )GetStateChildCount( )
Creates a child node under the node on which this method is called.
Syntax
public IState2 createStateChild(
String pName,
int Timeout,
int dwFlags)
HRESULT CreateStateChild(
LPCSTR pName,
ULONG Timeout,
DWORD dwFlags,
IGXState2 **ppChild);
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.
- 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.
The default scope is distributed and the default timeout is 60 seconds from the time the node was last accessed.
ppChild. A pointer to the created IGXState2 object. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use createStateChild( )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( )GetStateTreeRoot( ) in the AppLogicGXAppLogic 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( )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.
- Parent nodes can only have a timeout value of 0.
Tips
- To traverse the state tree to find the desired location in which to create a new child node, use getStateChild( )GetStateChild( ). Each successive call to getStateChild( )GetStateChild( ) descends one level in the tree.
Return Value
An IState2 object, or null for failure.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
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)
HRESULT DeleteStateChild(
LPCSTR pName);
pName. The name of the child node to delete.
Usage
Use deleteStateChild( )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( )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( )GetStateChild( ). Each successive call to getStateChild( )GetStateChild( ) descends one level in the tree.
Return Value
GXE.SUCCESS if the method succeeds.
Syntax
public IState2 getStateChild(
String pName)
HRESULT GetStateChild(
LPCSTR pName,
IGXState2 **ppChild);
pName. The name of the child node to get.
ppChild. A pointer to the retrieved IGXState2 object. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use getStateChild( )GetStateChild( ) to retrieve a node whose content you want to get or update. Your application component can also use getStateChild( )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.
HRESULT GetStateChildCount(
DWORD dwFlags,
ULONG *pCount);
pCount. Pointer to where the child count is returned.
Usage
Use this method to return the number of children at any given state node.
Return Value
An integer representing the number of children.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
"Using the State Layer"
Gets the contents of the node.
Syntax
public IValList getStateContents()
HRESULT GetStateContents(
IGXValList **ppContents);
ppContents. Pointer to the returned IGXValList that contains the contents of the current child node. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use getStateContents( )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( )SaveState( ).
- To traverse the state tree to find a specific node, use getStateChild( )GetStateChild( ). Each successive call to getStateChild( )GetStateChild( ) descends one level in the tree.
- If you update the contents of a node with setStateContents( )SetStateContents( ) but do not save the contents in the distributed store with saveState( )SaveState( ), getStateContents( )GetStateContents( ) will not return the content set with setStateContents( )SetStateContents( ). It will return the contents that were last saved.
Return Value
An IValList object that contains the contents, or null for failure.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
"Using the State Layer"
Gets the flags assigned to the node when it was created.
Syntax
public int getStateFlags()
HRESULT GetStateFlags(
DWORD *pdwFlags);
pdwFlags. Pointer to the client-allocated variable that contains the returned state flag.
Usage
Use getStateFlags( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
"Using the State Layer"
Syntax
public String getStateName()
HRESULT GetStateName(
LPSTR pName,
ULONG nName);
pName. Pointer to the buffer allocated by the client to store the returned node name.
nName. The size of the buffer to store the node name.
Usage
Use getStateName( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
"Using the State Layer"
Returns the node's timeout value in seconds.
Syntax
public int getStateTimeout()
HRESULT GetStateTimeout(
ULONG *pTimeout);
pTimeout. Pointer to the buffer allocated by the client to store the returned timeout value.
Usage
Use getStateTimeout( )GetStateTimeout( ) in conjunction with getStateFlags( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
"Using the State Layer"
Saves updates to the node contents.
Syntax
public int saveState(
int dwFlags)
HRESULT SaveState(
DWORD dwFlags);
dwFlags. Specify 0 (zero). Internal use only.
Usage
Use saveState( )SaveState( ) after you set or change the contents of a node. This method flushes the node contents into the distributed store.
Tip
The getStateContents( )GetStateContents( ) method retrieves the contents that were last saved in the distributed store with saveState( )SaveState( ). Therefore, if you update the contents of a node with setStateContents( )SetStateContents( ), but do not call saveState( )SaveState( ), getStateContents( )GetStateContents( ) will not return the content set with setStateContents( )SetStateContents( ).
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
"Using the State Layer"
Syntax
public int setStateContents(
IValList pContents)
HRESULT SetStateContents(
IGXValList *pContents);
pContents. Pointer to the IGXValList of values to set in the current node.
IValList of values to set in the current node.
Usage
Use setStateContents( )SetStateContents( ) to update the contents of a node.
- To traverse the state tree to find the child node to update, use getStateChild( )GetStateChild( ). Each successive call to getStateChild( )GetStateChild( ) descends one level in the tree.
- Call saveState( )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( )SetStateContents( ) several times before calling saveState( )SaveState( ), only the value from the last setStateContents( )SetStateContents( ) call is saved.
- The getStateContents( )GetStateContents( ) method retrieves the contents that were last saved in the distributed store with saveState( )SaveState( ). Therefore, if you update the contents of a node with setStateContents( )SetStateContents( ), but do not call saveState( )SaveState( ), getStateContents( )GetStateContents( ) will not return the content set with setStateContents( )SetStateContents( ).
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
The following code shows how to create a child node and set its contents:
IState2 tree = getStateTreeRoot(GXSTATE.GXSTATE_DISTRIB, "Grammy");
IState2 child = tree.getStateChild("Best Female Vocal");
child = tree.createStateChild("Best Female Vocal", 0,
IValList val = GX.CreateValList();
val.setValString("winner", "Whitney Houston");
val.setValString("runner up", "Barbara Streisand");
hr = GetStateTreeRoot(GXSTATE_DISTRIB, "Grammy", &m_pStateRoot);
if (hr == NOERROR && m_pStateRoot)
hr = m_pStateRoot->GetStateChild("Best Female Vocal",
hr = m_pStateRoot->CreateStateChild("Best Female Vocal",
pState->GetStateContents(&pVL);
IGXValList *pVL = GXCreateValList();
pVL->SetValString("winner", "Whitney Houston");
pVL->SetValString("runnerup", "Barbara
hr = pState->SetStateContents(pVL);
Related Topics
"Using the State Layer"
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 IStreamBufferIGXStreamBuffer 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( )EvalOutput( ) method in the AppLogicGXAppLogic class and pass in an IStreamIGXStream object. To manipulate the data in the stream buffer, use the getStreamData( )GetStreamData( ) method in this interface.
To create an instance of the IStreamBufferIGXStreamBuffer interface, use the GX.CreateStreamBuffer( )GXCreateStreamBuffer( ) methodhelper function.
Package Include File
com.kivasoft gxstream.h
Returns an array of byte values from the stream buffer.
Syntax
public byte[] getStreamData(
int flags)
HRESULT GetStreamData(
DWORD flags,
LPBYTE pBuff,
ULONG nBuff);
pBuff. Pointer to the client-allocated buffer to store the data.
nBuff. Length of the client-allocated buffer.
Usage
Use getStreamData( )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( )GetStreamData( ) after evalOutput( )EvalOutput( ) in the AppLogicGXAppLogic class. The evalOutput( )EvalOutput( ) method captures output in the stream buffer if the AppLogic passes in an IStreamIGXStream object.
Return Value
Array of byte values, or null for failure.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
evalOutput( )EvalOutput( ) in the AppLogic class (deprecated)GXAppLogic class
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 ITableIGXTable interface represents the definition of a table that is part of a relational data source. ITableIGXTable provides methods to perform the following types of operations:
- Add, update, and delete rows in the table.
- 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)IGXColumn interface.
The ITableIGXTable interface is part of the Data Access Engine (DAE) service.
To create an instance of the ITableIGXTable interface, use getTable( )GetTable( ) in the IDataConn Interface (deprecated)IGXDataConn interface or getTable( )GetTable( ) in the IColumn Interface (deprecated)IGXColumn interface.
Each call to getTable( )GetTable( ) returns a new ITableIGXTable object rather than returning an existing table object.
Package Include File
com.kivasoft gxidata.h
Example
// Add a new user to the User table
ITable 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)
HRESULT AddRow(
DWORD dwFlags,
IGXTrans *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. ITransPointer to the IGXTrans object that contains the transaction associated with this insert operation, or nullNULL.
Usage
Use addRow( )AddRow( ) to insert a new record into a table.
- Before adding a row, the AppLogic must first call allocRow( )AllocRow( ) to create a row buffer.
- Next, the AppLogic must specify data values for the new row by calling any of the setValueXXX( )SetValueXXX( ) methods, such as setValueString( )SetValueString( ) or setValueBinary( )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)IGXTrans interface using createTrans( )CreateTrans( ) in the AppLogic class (deprecated)GXAppLogic class. The AppLogic must then call begin( )Begin( ) before executing the statement and, after executing the statement, call commit( )Commit( ) or rollback( )Rollback( ) as appropriate.
Tips
- To determine whether a column is defined as NOT NULL, use getNullsAllowed( )GetNullsAllowed( ) in the IColumn Interface (deprecated)IGXColumn interface.
- Alternatively, the AppLogic can insert records by passing a SQL INSERT statement using setSQL( )SetSQL( ) in the IQuery Interface (deprecated)IGXQuery interface. 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).
HRESULT, which is set to 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);
if(((hr=pConn->GetTable("OBTransaction", &pTable))==GXE_SUCCESS)&&pTable) {
// Look up the column ordinals for the table
pTable->GetColumnOrdinal("transType", &transTypeCol);
pTable->GetColumnOrdinal("postDate", &postDateCol);
pTable->GetColumnOrdinal("acctNum", &acctNumCol);
pTable->GetColumnOrdinal("amount", &amountCol);
if(((hr=CreateTrans(&pTx))==GXE_SUCCESS)&&pTx) {
pTable->SetValueString(acctNumCol, pFromAcct);
pTable->SetValueInt(transTypeCol,TRANSTYPE_WITHDRAWAL);
pTable->SetValueDateString(postDateCol, dateStr);
pTable->SetValueDouble(amountCol, amount*-1.0);
if(pTable->AddRow(0, pTx)==GXE_SUCCESS) {
Related Topics
ITrans Interface (deprecated)IGXTrans interface
Allocates a new, empty row buffer, replacing the previous row buffer if one exists.
Usage
Use allocRow( )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( )AddRow( ) or to one or more existing records using updateRow( )UpdateRow( ).
- The AppLogic must call allocRow( )AllocRow( ) before specifying column values with a setValueXXX( )SetValueXXX( ) method.
- The AppLogic must call allocRow( )AllocRow( ) every time before calling addRow( )AddRow( ) or updateRow( )UpdateRow( ).
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to 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);
if(((hr=pConn->GetTable("OBTransaction", &pTable))==GXE_SUCCESS)&&pTable) {
// Look up the column ordinals for the table
pTable->GetColumnOrdinal("transType", &transTypeCol);
pTable->GetColumnOrdinal("postDate", &postDateCol);
pTable->GetColumnOrdinal("acctNum", &acctNumCol);
pTable->GetColumnOrdinal("amount", &amountCol);
if(((hr=CreateTrans(&pTx))==GXE_SUCCESS)&&pTx) {
pTable->SetValueString(acctNumCol, pFromAcct);
pTable->SetValueInt(transTypeCol,TRANSTYPE_WITHDRAWAL);
pTable->SetValueDateString(postDateCol, dateStr);
pTable->SetValueDouble(amountCol, amount*-1.0);
if(pTable->AddRow(0, pTx)==GXE_SUCCESS) {
Deletes one or more rows in the table.
Syntax
public int deleteRow(
int dwFlags,
String szWhere,
ITrans pTrans)
HRESULT DeleteRow(
DWORD dwFlags,
LPSTR szWhere,
IGXTrans *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. ITransPointer to the IGXTrans object that contains the transaction associated with this delete operation, or nullNULL.
- 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)IGXTrans interface using createTrans( )CreateTrans( ) in the AppLogic class (deprecated)GXAppLogic class. The AppLogic must then call begin( )Begin( ) before executing the statement and, after executing the statement, call commit( )Commit( ) or rollback( )Rollback( ) as appropriate.
Tip
Alternatively, the AppLogic can delete records by passing a SQL DELETE statement using setSQL( )SetSQL( ) in the IQuery Interface (deprecated)IGXQuery interface, then executing the query. The statement must comply with ANSI 92 SQL syntax.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to 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);
conn_params = GXCreateValList();
conn_params->SetValString("DSN", "salesDB");
conn_params->SetValString("DB", "salesDB");
conn_params->SetValString("USER", "steve");
conn_params->SetValString("PSWD", "pass7878");
hr = CreateDataConn(0, GX_DA_DRIVER_ODBC, conn_params, NULL, &conn);
hr = conn->GetTable("employees", &table);
table->DeleteRow(0, "lastname='Smith'", NULL);
Related Topics
ITrans Interface (deprecated)IGXTrans interface
"Deleting Records From a Database"
"Using Pass-Through Database Commands"
Resets the column enumeration to the first column in the table.
Syntax
public int enumColumnReset()
Usage
Use enumColumnReset( )EnumColumnReset( ) before iterating through and retrieving columns in a table. enumColumnReset( )EnumColumnReset( ) ensures that column retrieval starts from the first column.
Thereafter, use enumColumns( )EnumColumns( ) to retrieve each column sequentially. Each enumColumns( )EnumColumns( ) call returns an IColumnIGXColumn object for the next column.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to 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 = ";
Related Topics
"Getting Information About Columns or Fields"
Returns the definition of the next column in the table.
Syntax
public IColumn enumColumns()
HRESULT EnumColumns(
IGXColumn **ppColumn);
ppColumn. Pointer to the IGXColumn object that contains the returned next column of data. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use enumColumns( )EnumColumns( ) when the column definition is unknown and required for subsequent operations. The AppLogic can use the returned IColumnIGXColumn 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( )EnumColumnReset( ) to ensure that enumColumns( )EnumColumns( ) starts with the first column in the table. Each subsequent enumColumns( )EnumColumns( ) call moves to the next sequential column in the table and retrieves its column definition in an IColumnIGXColumn object.
- The columns might not be returned in the order in which they are defined in the database catalog.
- Test for nullNULL 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).
HRESULT, which is set to 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 = ";
Related Topics
IColumn Interface (deprecated)IGXColumn interface
"Getting Information About Columns or Fields"
Returns the definition of a column with the specified name.
Syntax
public IColumn getColumn(
String szColumn)
HRESULT GetColumn(
LPSTR szColumn,
IGXColumn **ppColumn);
szColumn. Name of the column to retrieve.
ppColumn. Pointer to the IGXColumn object that contains the returned column definition. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use getColumn( )GetColumn( ) when the column definition is unknown but its name is known. The AppLogic can use the IColumnIGXColumn 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).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
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)IGXColumn interface
"Getting Information About Columns or Fields"
Returns the definition of the column in the specified ordinal position.
Syntax
public IColumn getColumnByOrd(
int Ordinal)
HRESULT GetColumnByOrd(
ULONG Ordinal,
IGXColumn **ppColumn);
Ordinal. Ordinal number (position) of the column in the table. The first column is 1, the second column is 2, and so on.
ppColumn. Pointer to the IGXColumn object that contains the returned column definition. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use getColumnByOrd( )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 IColumnIGXColumn 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( )GetColumnByOrd( ), call getNumColumns( )GetNumColumns( ) to determine the maximum number of columns in the table, then proceed sequentially through each column using getColumnByOrd( )GetColumnByOrd( ), beginning with column 1, through the last column.
- Alternatively, call enumColumnReset( )EnumColumnReset( ) to start with the first column in the table, then call enumColumns( )EnumColumns( ) repeatedly through the last column.
Return Value
IColumn object for the specified column, or null for failure (such as an invalid column number).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
// Obtain information about all columns in the table
ITable tbl = conn.getTable("Products");
int maxCols = tbl.getNumColumns();
IColumn col = tbl.getColumnByOrd(i);
. . . manipulate column using IColumn methods . . .
Related Topics
IColumn Interface (deprecated)IGXColumn interface
"Getting Information About Columns or Fields"
Returns the ordinal position of the column specified by name.
Syntax
public int getColumnOrdinal(
String szColumn)
HRESULT GetColumnOrdinal(
LPSTR szColumn,
ULONG *pOrdinal);
pOrdinal. Pointer to the buffer allocated by the client to contain the returned ordinal position of the specified column. The first column is 1, the second column is 2, and so on.
Usage
Use getColumnOrdinal( )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**( )SetValue**( ) methods, such as setValueString( )SetValueString( ) and setValueInt( )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.
HRESULT, which is set to 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");
if(((hr=GetOBDataConn(&pConn))==GXE_SUCCESS)&&pConn) {
if(((hr=pConn->GetTable("OBTransaction",
&pTable))==GXE_SUCCESS)&&pTable) {
// Look up the column ordinals for the table
pTable->GetColumnOrdinal("transType", &transTypeCol);
pTable->GetColumnOrdinal("postDate", &postDateCol);
pTable->GetColumnOrdinal("acctNum", &acctNumCol);
pTable->GetColumnOrdinal("amount", &amountCol);
Related Topics
IColumn Interface (deprecated)IGXColumn interface
"Getting Information About Columns or Fields"
Returns the data connection object associated with the data source in which the table is defined.
Syntax
public IDataConn getDataConn()
HRESULT GetDataConn(
IGXDataConn **ppDataConn);
ppDataConn. Pointer to the IGXDataConn object that contains the returned data connection object associated with the data source in which the table is defined. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use getDataConn( )GetDataConn( ) when the data connection associated with the table is unknown and is required for subsequent operations.
Tip
The IDataConnIGXDataConn object that getDataConn( )GetDataConn( ) returns may not be equal (==) to the IDataConnIGXDataConn object that createDataConn( )CreateDataConn( ), in the AppLogic class (deprecated)GXAppLogic class, returned.
Return Value
IDataConn object for the table, or null for failure.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
IDataConn Interface (deprecated)
Returns the name of the table.
Syntax
public String getName()
HRESULT GetName(
LPSTR pBuff,
ULONG nBuff);
pBuff. Pointer to the buffer allocated by the client to contain the returned table name.
nBuff. The length of the pBuff buffer, in bytes.
Usage
Use getName( )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).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Returns the number of columns in the table object.
Syntax
public int getNumColumns()
HRESULT GetNumColumns(
ULONG *pnCols);
pnCols. Pointer to the returned number of columns in the table.
Usage
Use getNumColumns( )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).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
// Obtain information about all columns in the table
ITable 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)
HRESULT SetValueBinary(
ULONG Ordinal,
LPBYTE pValue,
ULONG nOffset,
ULONG 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( )SetValueBinary( ) for BINARY data of which the total size is equal to or smaller than 64K.
- The AppLogic must call allocRow( )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( )SetValueBinaryPiece( ) for LONGBINARY, LONGVARBINARY, or equivalent type values.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to 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)
HRESULT SetValueBinary(
ULONG Ordinal,
LPBYTE pValue,
ULONG nOffset,
ULONG 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( )SetValueBinaryPiece( ) to specify LONGBINARY data. LONGBINARY data must be added in 64K increments, therefore, you must use setValueBinaryPiece( )SetValueBinaryPiece( ) several times to add the data.
- The AppLogic must call allocRow( )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( )AllocRow( ) but before addRow( )AddRow( ) or updateRow( )UpdateRow( ).
Tip
Use setValueBinary( )SetValueBinary( ) for BINARY, VARBINARY, or equivalent type values.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to 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)
HRESULT SetValueDateString(
ULONG Ordinal,
LPSTR 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"
The subseconds (,999 in the example) and time zone (PDT in the example) are optional.
- "1997-10-01 14:35:59.999"
The time is optional.
Rule
The AppLogic must call allocRow( )AllocRow( ) before attempting to write to the row buffer.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to 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);
if(((hr=pConn->GetTable("OBTransaction", &pTable))==GXE_SUCCESS)&&pTable) {
pTable->GetColumnOrdinal("postDate", &postDateCol);
// Allocate a new row and set a datestring value
pTable->SetValueDateString(postDateCol, dateStr);
Specifies the double value of a column in the row buffer.
Syntax
public int setValueDouble(
int Ordinal,
double nValue)
HRESULT SetValueDouble(
ULONG 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( )AllocRow( ) before attempting to write to the row buffer.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to 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);
if(((hr=pConn->GetTable("OBTransaction", &pTable))==GXE_SUCCESS)&&pTable) {
pTable->GetColumnOrdinal("amount", &amountCol);
// Allocate a new row and set a double value
pTable->SetValueDouble(amountCol, amount*-1.0);
Specifies the int value of a column in the row buffer.
Syntax
public abstract int setValueInt(
int Ordinal,
int nValue)
HRESULT SetValueInt(
ULONG Ordinal,
DWORD 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( )AllocRow( ) before attempting to write to the row buffer.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to 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);
if(((hr=pConn->GetTable("OBTransaction", &pTable))==GXE_SUCCESS)&&pTable) {
pTable->GetColumnOrdinal("transType", &transTypeCol);
// Allocate a new row and set an int value
pTable->SetValueInt(transTypeCol, TRANSTYPE_WITHDRAWAL);
Specifies the String value of a column in the row buffer.
Syntax
public int setValueString(
int Ordinal,
String pValue)
HRESULT SetValueString(
ULONG Ordinal,
LPSTR 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.
Pointer to the variable that contains the string expression to assign to the column.
Rule
The AppLogic must call allocRow( )AllocRow( ) before attempting to write to the row buffer.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to 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);
if(((hr=pConn->GetTable("OBTransaction", &pTable))==GXE_SUCCESS)&&pTable) {
pTable->GetColumnOrdinal("acctNum", &acctNumCol);
// Allocate a new row and set a string value
pTable->SetValueString(acctNumCol, pFromAcct);
Specifies a TEXT value of a column in the row buffer.
Syntax
public int setValueText(
int Ordinal,
String pValue,
int nOffset,
int nLength)
HRESULT SetValueText(
ULONG Ordinal,
LPSTR pValue,
ULONG nOffset,
ULONG 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( )SetValueText( ) for TEXT data, or database equivalent, of which the total size is equal to or smaller than 64K.
- The AppLogic must call allocRow( )AllocRow( ) before attempting to write to the row buffer.
- The data type of the column must be TEXT or database equivalent.
Tip
Use setValueTextPiece( )SetValueTextPiece( ) for LONGTEXT or equivalent type values.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to 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)
HRESULT SetValueText(
ULONG Ordinal,
LPSTR pValue,
ULONG nOffset,
ULONG 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( )SetValueTextPiece( ) for LONGTEXT data. LONGTEXT values must be added in 64K increments, therefore, you must call setValueTextPiece( )SetValueTextPiece( ) repeatedly to add the data.
- The AppLogic must call allocRow( )AllocRow( ) before attempting to write to the row buffer.
- The data type of the column must be LONGTEXT or database equivalent.
Tip
Use setValueText( )SetValueText( ) for TEXT or equivalent type values.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to 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)
HRESULT UpdateRow(
DWORD dwFlags,
LPSTR szWhere,
IGXTrans *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 Pointer to the IGXTrans object that contains the transaction associated with this update operation, or nullNULL.
- Before modifying a row, the AppLogic must first call allocRow( )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( )SetValueDateString( ), setValueDouble( )SetValueDouble( ), setValueInt( ) SetValueInt( ), or setValueString( )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)IGXTrans interface using createTrans( )CreateTrans( ) in the AppLogic class (deprecated)GXAppLogic class. The AppLogic must then call begin( )Begin( ) before executing the statement and, after executing the statement, call commit( )Commit( ) or rollback( )Rollback( ) as appropriate.
Tips
- The updateRow( )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( )GetNullsAllowed( ) in the IColumn Interface (deprecated)IGXColumn interface.
- Alternatively, the AppLogic can update records by passing a SQL INSERT statement using setSQL( )SetSQL( ) in the IQuery Interface (deprecated)IGXQuery interface. The statement must comply with ANSI 92 SQL syntax.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
// Obtain the definition for the Catalog table
ITable 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);
conn_params = GXCreateValList();
conn_params->SetValString("DSN", "salesDB");
conn_params->SetValString("DB", "salesDB");
conn_params->SetValString("USER", "steve");
conn_params->SetValString("PSWD", "pass7878");
hr = CreateDataConn(0, GX_DA_DRIVER_ODBC, conn_params, NULL, &conn);
hr = conn->GetTable("employees", &table);
table->GetColumnOrdinal("region", &col);
table->SetValueString(col, "East");
table->UpdateRow(0, "region='West'", NULL);
Related Topics
ITrans Interface (deprecated)IGXTrans interface
"Updating Records in a Database"
"Using Pass-Through Database Commands"
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 ITemplateDataIGXTemplateData interface represents a hierarchical source of data used for HTML template processing. ITemplateData IGXTemplateData provides methods for iterating through rows in a set of memory-based hierarchical data and retrieving column values.
To create an ITemplateData IGXTemplateData object, an AppLogic calls GX.CreateTemplateDataBasic( )the GXCreateTemplateDataBasic( ) helper function. The AppLogic populates the ITemplateData IGXTemplateData object with rows of hierarchical data, then passes this ITemplateDataBasicGXTemplateDataBasic object as the datadata parameter in evalTemplate( )EvalTemplate( ) or evalOutput( )EvalOutput( ) in the AppLogic class (deprecated)GXAppLogic class. The Template Engine then draws upon the hierarchical data during template processing using methods in the ITemplateData IGXTemplateData 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)GXTemplateDataBasic class and override the ITemplateDataIGXTemplateData member methods.
Package Include File
com.kivasoftgxitmpl.h
Example
// Determine whether AppLogic module is listed in project
name = 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( )EvalTemplate( ) and evalOutput( )EvalOutput( ) in the AppLogic class (deprecated)GXAppLogic class
TemplateDataBasic class (deprecated) GXTemplateDataBasic class
"Constructing a Hierarchical Result Set with GXTemplateDataBasic"
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)
HRESULT GetValue(
LPSTR szExpr,
IGXBuffer **ppBuff);
szExpr. Name of a field in the template data object.
ppBuff. Pointer to the IGXBuffer object that will contain the returned value of the specified field in the current row. After the function is done, the returned buffer should hold a zero-terminated string. This method allocates the IGXBuffer object automatically. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
The Template Engine calls getValue( )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( )IsEmpty( ) to determine whether rows were returned. Next, for each row in the result set, call getValue( ) GetValue( ) to retrieve field values, then call moveNext( )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 interfaceIGXBuffer 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).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
evalTemplate( )EvalTemplate( ) and evalOutput( )EvalOutput( ) in the AppLogic class (deprecated)GXAppLogic class
TemplateDataBasic class (deprecated) GXTemplateDataBasic class
"Constructing a Hierarchical Result Set with GXTemplateDataBasic"
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)
HRESULT IsEmpty(
LPSTR group,
BOOL *empty);
group. Name of a group in the hierarchical result set.
Usage
The Template Engine calls isEmpty( )IsEmpty( ) to test whether the specified group in the ITemplateDataIGXTemplateData object contains any rows of data before processing individual fields using getValue( )GetValue( ).
Rule
The specified group name must exist in the hierarchical data set.
Tip
When processing result sets, first call isEmpty( )IsEmpty( ) to determine whether rows were returned. Next, for each row in the result set, call getValue( )GetValue( ) to retrieve field values, then call moveNext( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
evalTemplate( )EvalTemplate( ) and evalOutput( )EvalOutput( ) in the AppLogic class (deprecated)GXAppLogic class
TemplateDataBasic class (deprecated) GXTemplateDataBasic class
"Constructing a Hierarchical Result Set with GXTemplateDataBasic"
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)
HRESULT MoveNext(
LPSTR group);
group. Name of a group to process in the hierarchical data of the template data object.
Usage
The Template Engine calls moveNext( ) 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( ) IsEmpty( ) to determine whether rows were returned. Next, for each row in the result set, call getValue( ) GetValue( ) to retrieve field values, then call moveNext( ) 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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
evalTemplate( )EvalTemplate( ) and evalOutput( )EvalOutput( ) in the AppLogic class (deprecated)GXAppLogic class
TemplateDataBasic class (deprecated) GXTemplateDataBasic class
"Constructing a Hierarchical Result Set with GXTemplateDataBasic"
The setHint( )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 ITemplateDataIGXTemplateData interface, implement setHint( )SetHint( ) to return 0.
Syntax
public int setHint(
String group,
int flags,
int max,
IValList pVal)
HRESULT SetHint(
LPSTR group,
DWORD flags,
ULONG max,
IGXValList *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 ITemplateMapIGXTemplateMap interface represents a mapping between a template field specification and dynamic data used for HTML template processing. ITemplateMapIGXTemplateMap provides the get( )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 GXCreateTemplateMapBasic( ) helper function. The AppLogic then populates the field map using put( )Put( ), in the TemplateMapBasic class (deprecated)GXTemplateMapBasic class, for each field mapping, then passes this ITemplateMapIGXTemplateMap object as the mapmap parameter in evalTemplate( )EvalTemplate( ) or evalOutput( )EvalOutput( ) in the AppLogic class (deprecated)GXAppLogic class. When the Template Engine encounters a GX markup tag with the id attribute while processing the template, it calls get( )Get( ) in the ITemplateMap Interface (deprecated)IGXTemplateMap interface 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)GXTemplateMapBasic class and override the getString( )Get( ) 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.
Package Include File
com.kivasoft gxitmpl.h
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( )EvalTemplate( ) and evalOutput( )EvalOutput( ) in the AppLogic class (deprecated)GXAppLogic class
TemplateMapBasic class (deprecated) GXTemplateDataBasic class
ITemplateData Interface (deprecated) IGXTemplateData interface
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)
HRESULT Get(
LPSTR szExpr,
IGXObject *pData,
IGXObject *pMark,
IGXBuffer **pBuff);
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 nullNULL. Internal use only.
pMark. Specify nullNULL. Internal use only.
pBuff. Pointer to the IGXBuffer object that contains the returned value. This method allocates the IGXBuffer object automatically. When AppLogic is finished using the object, call the Release( ) method to release the interface instance.
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( )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)GXTemplateMapBasic class and override getString( )Get( ) 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.
Rule
An AppLogic should use Get( ) only to override it after subclassing the GXTemplateMapBasic class.
Tip
Use methods in the IGXBuffer interface to manipulate the memory block.
Return Value
An IBuffer object that contains the value of the id mapping, or null for failure.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
evalTemplate( )EvalTemplate( ) and evalOutput( )EvalOutput( ) in the AppLogic class (deprecated)GXAppLogic class
getString( ) in theTemplateMapBasic class (deprecated) GXTemplateDataBasic class
ITemplateData Interface (deprecated) IGXTemplateData interface
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 ITileIGXTile 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( ) methodGXProcessOutput( ) helper function.
AppLogics use ITileIGXTile together with GX.ProcessOutput( )GXProcessOutput( ) 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( )NewRequest( ).
- Through newRequest( )NewRequest( ), the client passes input and output IValListsIGXValLists to the called AppLogic. If the client is an AppLogic, it specifies the value "ocl" for the gx_client_type key in the input IValListIGXValList.
- The called AppLogic processes the request and sends back results using its output IValListIGXValList or by calling evalOutput( )EvalOutput( ).
- The client calls the GX.ProcessOutput( ) methodGXProcessOutput( ) helper function to process the results into an ITileIGXTile object.
- Using methods in the ITileIGXTile interface, the client traverses the tile and retrieves values to populate user interface controls, such as text boxes or list boxes, on a form.
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( )EvalOutput( ). The tile tag determines the tile or record set, and the cell tag, the values in each record.
Package Include File
com.kivasoft gxcipm.h
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( )GXProcessOutput( ) and ITileIGXTile 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();
hr = pConn->NewRequest(guid, vIn, vOut, 0);
printf("Failed to invoke NewRequest()\n");
// Get the root tile from the output vallist
hr = GXProcessOutput(NULL, 0, vOut, &mainTile);
//Iterate over all categories and print their names
if ((hr = mainTile->GetTileChild("CATEGORIES", &ptile)) != NOERROR)
printf("Unable to get tile child, hr = %d\n", hr);
while (ptile && hr == NOERROR)
hr = ptile->GetTileValue("CATEGORIES.Name", sval, sizeof(sval));
for (int i=0; i < (depth * 2); i++)
printf("Category %s\n", sval);
hr = ptile->GetTileValue("CATEGORIES.CategoryId", sval,
test_Catalog(pConn, sval, depth+1);
hr = ptile->MoveTileNextRecord();
Related Topics
newRequest( )NewRequest( ) and evalOutput( )EvalOutput( ) in the AppLogic class (deprecated)GXAppLogic class
GX.ProcessOutput( )GXProcessOutput( ),
IValList Interface (deprecated)IGXValList interface
Syntax
public ITile getTileChild(
String name)
HRESULT GetTileChild(
LPSTR name,
IGXTile **tile);
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.
tile. A pointer to the retrieved IGXTile object. When the client is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use getTileChild( )GetTileChild( ) to retrieve a tile from which to get records and record values. Use it in conjunction with moveTileNextRecord( )MoveTileNextRecord( ) and getTileValue( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
getTileValue( )GetTileValue( ),
moveTileNextRecord( )MoveTileNextRecord( )
Returns the value of a specified field in a record.
Syntax
public String getTileValue(
String name)
HRESULT GetTileValue(
LPSTR name,
LPSTR value,
ULONG valuelen);
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.
value. Pointer to a buffer allocated by the client to store the returned string value.
valuelen. The size of the buffer to store the value.
Usage
Use getTileValue( )GetTileValue( ) to retrieve values in a record. Use it in conjunction with getTileChild( )GetTileChild( ) and moveTileNextRecord( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
getTileChild( )GetTileChild( ),
moveTileNextRecord( )MoveTileNextRecord( )
Moves to the next record in the tile.
Syntax
public int moveTileNextRecord()
Usage
Use moveTileNextRecord( )MoveTileNextRecord( ) to go to the next record in a tile after retrieving values in the current record. Use the method in conjunction with getTileChild( )GetTileChild( ) and getTileValue( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
getTileChild( )GetTileChild( ),
getTileValue( )GetTileValue( )
Moves to a specific record in the tile.
Syntax
public int moveTileNextRecord(
int ord)
HRESULT MoveTileToRecord(
ULONG 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( )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( )MoveTileToRecord( ) to display only several records at a time.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to 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 ITransIGXTrans interface represents a transaction object used for subsequent transaction processing operations. ITransIGXTrans provides operations for beginning, committing, and rolling back transactions.
After instantiating a transaction object, the AppLogic calls begin( )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)IGXTable interface. Finally, the AppLogic closes the transaction by calling either commit( )Commit( ) to save all changes or rollback( )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 IGXTrans interface, use createTrans( )CreateTrans( ) in the AppLogic class (deprecated)GXAppLogic class, as shown in the following example:.
Package Include File
com.kivasoft gxitrans.h
Example
// Create and begin a transaction
if(!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
// Create a transaction for several insert operations
if(((hr=CreateTrans(&pTx))==GXE_SUCCESS)&&pTx) {
if(((hr=pUserPQuery->Execute(0, pUserValList, pTx, NULL,
&pRset))==GXE_SUCCESS)&&pRset) {
// The result set is not needed; release it
if(((hr=pCustPQuery->Execute(0, pCustValList, pTx, NULL,
&pRset))==GXE_SUCCESS)&&pRset) {
// All is ok. Commit the transaction
GXSetValListString(m_pValIn, "ssn", m_pSsn);
GXSetValListString(m_pValIn, "OUTPUTMESSAGE", "Successfully
if(NewRequest("AppLogic CShowCustPage", m_pValIn, m_pValOut,
HandleOBSystemError("Could not chain to CShowCustPage
HandleOBSystemError("Could not insert checking account record
HandleOBSystemError("Could not insert checking account record for
HandleOBSystemError("Could not start transaction");
Related Topics
createTrans( )CreateTrans( ) in the AppLogic class (deprecated)GXAppLogic class
addRow( )AddRow( ), updateRow( )UpdateRow( ), and deleteRow( )DeleteRow( ) in the ITable Interface (deprecated)IGXTable interface
"Managing Database Transactions"
Usage
Use begin( )Begin( ) to start a transaction before performing any operations in the transaction. Subsequent operations belong to the current transaction until either commit( )Commit( ) or rollback( )Rollback( ) is called.
- AppLogic must start the transaction explicitly using begin( )Begin( ) before performing any query, insert, update, or delete operations associated with the transaction.
- AppLogic must complete the transaction explicitly by calling commit( )Commit( ) to save any changes to tables or rollback( )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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
// Create a transaction
ITrans updCustTrans = createTrans();
return handleOBSystemError("Could not create transaction");
if(((hr=CreateTrans(&pTx))==GXE_SUCCESS)&&pTx) {
Related Topics
createTrans( )CreateTrans( ) in the AppLogic class (deprecated)GXAppLogic class
addRow( )AddRow( ), updateRow( )UpdateRow( ), and deleteRow( )DeleteRow( ) in the ITable Interface (deprecated)IGXTable interface
"Managing Database Transactions"
Commits the transaction, saving any changes.
Syntax
public IObject commit(
int dwFlags)
HRESULT Commit(
DWORD dwFlags,
IGXObject **ppEvent);
ppEvent. Specify NULL. Internal use only.
Usage
Use commit( )Commit( ) to commit a transaction and write unsaved changes to disk. commit( )Commit( ) saves the changes, terminates the transaction object, and releases system resources.
- The AppLogic must start the transaction explicitly by calling begin( )Begin( ) before any changes associated with the transaction can be committed.
- The AppLogic must complete the transaction explicitly by calling commit( )Commit( ) to save any changes to tables or rollback( )Rollback( ) to abandon them.
- The AppLogic cannot reuse an ITrans IGXTrans object that has been committed. It must create a new one using createTrans( )CreateTrans( ) in the AppLogic class (deprecated)GXAppLogic class.
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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
// Update Customer record
rs = 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.");
if(((hr=pCustPQuery->Execute(0, pCustValList, pTx, NULL, &pRset))==GXE_SUCCESS)&&pRset) {
// Operation succeeded. Commit the transaction.
GXSetValListString(m_pValIn, "OUTPUTMESSAGE", "Successfully updated
Related Topics
createTrans( )CreateTrans( ) in the AppLogic class (deprecated)GXAppLogic class
addRow( )AddRow( ), updateRow( )UpdateRow( ), and deleteRow( )DeleteRow( ) in the ITable Interface (deprecated)IGXTable interface
"Managing Database Transactions"
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( )Begin( ) before any changes associated with the transaction can be rolled back.
- The AppLogic must complete the transaction explicitly by calling commit( )Commit( ) to save any changes to tables or rollback( )Rollback( ) to abandon them.
- The AppLogic cannot reuse an ITrans IGXTrans object that has been rolled back. It must create a new one using createTrans( )CreateTrans( ) in the AppLogic class (deprecated)GXAppLogic class.
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.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
rs = updUserPQuery.execute(0, userValList, updCustTrans, null);
return handleOBSystemError("Could not update User.");
if(((hr=pUserPQuery->Execute(0, pUserValList, pTx, NULL, &pRset))==GXE_SUCCESS)&&pRset) {
// Query succeeded. Perform update.
HandleOBSystemError("Could not insert checking account record for new
Related Topics
createTrans( )CreateTrans( ) in the AppLogic class (deprecated)GXAppLogic class
addRow( )AddRow( ), updateRow( )UpdateRow( ), and deleteRow( )DeleteRow( ) in the ITable Interface (deprecated)IGXTable interface
"Managing Database Transactions"
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 IValListIGXValList 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 IGXValList 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) GXAppLogic class defines two member variables, valIn m_pValIn and valOutm_pValOut, to contain the input arguments and output values, respectively, of AppLogic execution.
In an IValListIGXValList, 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 IValListIGXValList by its key name. Key names are unique within each IValListIGXValList object.
The IValList interface IGXValList interface provides methods for adding, retrieving, removing, and counting GXVAL objects in the IValList IGXValList instance. Using methods in the IValList interfaceIGXValList 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 IGXValList interface, use the GX.CreateValList( )GXCreateValList( ) methodfunction.
Package Include File
com.kivasoft gxival.h
Related Topics
GXVAL struct
valInm_pValIn and valOutm_pValOut in the AppLogic class (deprecated)GXAppLogic class
execute( ) execute( ) in the AppLogic class (deprecated) GXAppLogic class
Returns the number of GXVAL objects in the IValList IGXValList.
HRESULT Count(
ULONG *pCount);
pCount. Pointer to the returned count of GXVAL objects.
Usage
When the contents of an IValListIGXValList are unknown, an AppLogic can iterate through each GXVAL object to test, retrieve, and update information. Use count( ) Count( ) to determine the maximum number of iterations needed to go completely through the IValList IGXValList.
Rule
Do not add or remove GXVAL objects to or from the IValList IGXValList when iterating through the IValList IGXValList.
- Use count( ) Count( ) in conjunction with getNextKey( )GetNextKey( ) and resetPosition( )ResetPosition( ) to iterate through the IValList IGXValList.
- Adding or deleting GXVAL objects changes the number of objects in a IValList IGXValList. 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).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
// Obtain the contents of the shopping basket
IValList 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( )GetNextKey( )
resetPosition( )ResetPosition( )
valInm_pValIn and valOutm_pValOut in the AppLogic class (deprecated)GXAppLogic class
execute( )Execute( ) in the AppLogic class (deprecated) GXAppLogic class
Retrieves the key name of the next GXVAL object in the IValList IGXValList.
Syntax
public String getNextKey()
HRESULT GetNextKey(
LPSTR pKey,
ULONG nKey);
pKey. Pointer to a buffer allocated by the client to store the returned key string.
nKey. The size of the buffer to store the key.
Usage
When the contents of a IValList IGXValList 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 IGXValList list.
Rule
Do not add or remove GXVAL objects to or from the IValList IGXValList when iterating through the IValList IGXValList.
Tip
Use getNextKey( ) GetNextKey( ) in conjunction with count( )Count( ) and resetPosition( )ResetPosition( ) to iterate through the IValList IGXValList.
Return Value
String representing the next retrieved key in the IValList, or null for failure (such as if no other keys exist).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
// Returns the contents of the shopping basket
public 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));
// Reset to the first GXVAL in the ValList before iteration
// Iterate through all the GXVALs in the
// vallist and print them to a file
while (pValList->GetNextKey(pKey, 256) == NOERROR) {
pValList->GetValByRef(pKey, &val);
if (GXVT_TYPE(val.vt) == GXVT_LPSTR)
fprintf(fp, "\t%s=%s (LPSTR)\n", pKey, val.u.pstrVal);
fprintf(fp, "\t%s=%d (DWORD)\n", pKey, val.u.ulVal);
Related Topics
count( )Count( )
resetPosition( )ResetPosition( )
execute( )Execute( ) in the AppLogic class (deprecated)GXAppLogic class
Copies the specified GXVAL object from the IValList IGXValList.
Syntax
public GXVAL getVal(
String pKey)
HRESULT GetVal(
LPSTR pKey,
GXVAL *pVal);
pKey. Key name of the GXVAL object to copy from the IValList IGXValList.
pVal. Pointer to the GXVAL allocated by the client to store the copy of the retrieved GXVAL object.
Usage
Use getVal( ) GetVal( ) if the data type of the GXVAL object is not known. Use getValString( )GetValString( ) instead for string objects, getValInt( )GetValInt( ) for integer objects, and getValBLOB( )GetValBLOB( ) for BLOB objects.
GetVal( ) makes a deep copy of the GXVAL object.
Rule
The specified key name must currently exist in the IValList IGXValList.
Tip
Use the GXVALClear( ) function to release a GXVAL object when the AppLogic no longer needs it.
Return Value
New GXVAL object representing a copy of the GXVAL object specified by pKey, or null for failure (such as invalid keyname).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
// Returns the contents of the shopping basket
public 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( )GetValBLOB( ), getValInt( )GetValInt( ), and getValString( )GetValString( ) in the IValList Interface (deprecated)IGXValList interface
valInm_pValIn and valOutm_pValOut in the AppLogic class (deprecated)GXAppLogic class
execute( )Execute( ) in the AppLogic class (deprecated)GXAppLogic class
Returns a specified BLOB object from the IValListIGXValList.
Syntax
public byte[] getValBLOB(
String pKey)
HRESULT GetValBLOB(
LPSTR pKey,
LPBYTE pVal,
ULONG nBufferLen);
pKey. Key name of the GXVAL object that contains the BLOB value to retrieve.
pVal. Pointer to a buffer allocated by the client to store the returned value.
nBufferLen. Length of the buffer allocated by the client.
Usage
Use getValBLOB( )GetValBLOB( ) when the type of a GXVAL object is a BLOB, but its value is not known and needed for subsequent operations. Use getValString( )GetValString( ) instead for string objects and getValInt( )GetValInt( ) for integer objects. If the type of the GXVAL object is not known, use getVal( )GetVal( ).
Rule
The data type must be TEXT, BINARY, VARBINARY, or database equivalent.
Tip
Call GetValBLOBSize( ) before GetValBLOB( ) to determine the size of the BLOB so the code can allocate the appropriate buffer size for it.
Return Value
A byte array for success, or null for failure.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
getValBLOBSize( )GetValBLOBSize( ) and setValBLOB( )SetValBLOB( ) in the IValList Interface (deprecated)IGXValList interface
Returns the size of a specified BLOB object in the IValListIGXValList.
Syntax
public int getValBLOBSize(
String pKey)
HRESULT GetValBLOBSize(
LPSTR pKey,
ULONG *pBuffLen);
pKey. Key name of the GXVAL object that contains the BLOB.
pBuffLen. Pointer to a buffer allocated by the client to store the returned value.
Usage
BLOB objects can be large. If you want to determine the size of a BLOB object before retrieving it, use getValBLOBSize( )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).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
getValBLOB( )GetValBLOB( )
Gets the specified GXVAL object from the IValList IGXValList.
Syntax
public GXVAL getValByRef(
string pKey)
HRESULT GetValByRef(
LPSTR pKey,
GXVAL *pVal);
pKey. Key name of the GXVAL object to get from the IValList IGXValList.
pVal. Pointer to the GXVAL allocated by the client to store the retrieved GXVAL object.
Usage
Use getValByRef( ) GetValByRef( ) if the data type of the GXVAL object is not known, or if iterating through an IValListIGXValList to get each GXVAL object. Use getValString( )GetValString( ) instead for string objects, getValInt( )GetValInt( ) for integer objects, and getValBLOB( )GetValBLOB( ) for BLOB objects.
GetValByRef( ) makes a shallow copy of the specified GXVAL object in the IGXValList. If you want a deep copy, call GetVal( ).
Return Value
New GXVAL object representing a copy of the GXVAL object specified by pKey, or null for failure (such as invalid keyname).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
// Reset to the first GXVAL in the ValList before iteration
// Iterate through all the GXVALs in the
// vallist, get each value and print it to a file
while (pValList->GetNextKey(pKey, 256) == NOERROR) {
pValList->GetValByRef(pKey, &val);
if (GXVT_TYPE(val.vt) == GXVT_LPSTR)
fprintf(fp, "\t%s=%s (LPSTR)\n", pKey, val.u.pstrVal);
fprintf(fp, "\t%s=%d (DWORD)\n", pKey, val.u.ulVal);
Related Topics
getValBLOB( )GetValBLOB( ), getValInt( )GetValInt( ), and getValString( )GetValString( ) in the IValList Interface (deprecated)IGXValList interface
valInm_pValIn and valOutm_pValOut in the AppLogic class (deprecated)GXAppLogic class
execute( )Execute( ) in the AppLogic class (deprecated)GXAppLogic class
Retrieves an integer value from the specified GXVAL object in the IValListIGXValList.
Syntax
public int getValInt(
String pKey)
HRESULT GetValInt(
LPSTR pKey,
LONG *pVal);
pKey. Key name of the GXVAL object from which to retrieve the integer value.
pVal. Pointer to a buffer allocated by the client to store the returned value.
Usage
Use getValInt( )GetValInt( ) if the data type of the GXVAL object is known to be an integer. Otherwise, use getValString( )GetValString( ) instead for string objects, getValBLOB( )GetValBLOB( ) for BLOB objects, or getVal( )GetVal( ) for objects of other types.
- The specified key name must currently exist in the IValListIGXValList.
- 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).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
// Obtains the User ID from the Session's IValList
return getValList().getValInt("UserId");
Related Topics
GXVAL struct
valInm_pValIn and valOutm_pValOut in the AppLogic class (deprecated)GXAppLogic class
execute( )Execute( ) in the AppLogic class (deprecated)GXAppLogic class
Retrieves a string value from the specified GXVAL object in the IValListIGXValList.
Syntax
public String getValString(
String pKey)
HRESULT GetValString(
LPSTR pKey,
LPSTR pBuff,
ULONG nBuff);
pKey. Key name of the GXVAL object from which to retrieve the string value.
pBuff. Pointer to a buffer allocated by the client to store the returned value.
nBuff. Length of the buffer allocated by the client.
Usage
Use getValString( )GetValString( ) when the data type of the GXVAL object is known to be a string. Otherwise, use getValInt( )GetVal( ) instead for integer objects, getValBLOB( )GetValBLOB( ) for BLOB objects, or getVal( )GetVal( ) for objects of other types.
- The specified key name must currently exist in the IValListIGXValList.
- 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).
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
// Obtain security information from the valIn IValList
String 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
GXVAL struct
valInm_pValIn and valOutm_pValOut in the AppLogic class (deprecated)GXAppLogic class
execute( )Execute( ) in the AppLogic class (deprecated)GXAppLogic class
Removes the specified GXVAL object from the IValList IGXValList.
Syntax
public int removeVal(
String pKey)
HRESULT RemoveVal(
LPSTR pKey);
pKey. Key name of the GXVAL object to remove from the IValList IGXValList.
Usage
Use removeVal( ) RemoveVal( ) to delete a GXVAL object that is no longer needed in the IValList IGXValList. 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 IGXValList.
- Do not remove GXVAL objects from the IValList IGXValList when iterating through the IValList IGXValList.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
// Empties the contents of the shopping basket
public 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( )SetVal( ) and resetPosition( )ResetPosition( ) in the IValList Interface (deprecated) IGXValList interface
valInm_pValIn and valOutm_pValOut in the AppLogic class (deprecated)GXAppLogic class
execute( )Execute( ) in the AppLogic class (deprecated)GXAppLogic class
Resets the iterator position to the "first" GXVAL object in the IValList IGXValList.
Syntax
public int resetPosition()
Usage
When the contents of an IValList IGXValList are unknown, the AppLogic can iterate through each GXVAL object and retrieve its key name. Before iterating through the IValList IGXValList, the AppLogic needs to call resetPosition( ) ResetPosition( ) once to ensure that iteration begins at the "first" GXVAL object in the IValList IGXValList.
Rule
Do not add or remove GXVAL objects to or from the IValList IGXValList when iterating through the IValList IGXValList.
- The first GXVAL object is not necessarily the first one added to the IValList IGXValList.
- Use resetPosition( ) ResetPosition( ) in conjunction with count( )Count( ) and getNextKey( )GetNextKey( ) to iterate through the IValList IGXValList.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
// Returns the contents of the shopping basket
public 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));
// Reset to the first GXVAL in the ValList before iteration
// Iterate through all the GXVALs in the
// vallist and print them to a file
while (pValList->GetNextKey(pKey, 256) == NOERROR) {
pValList->GetValByRef(pKey, &val);
if (GXVT_TYPE(val.vt) == GXVT_LPSTR)
fprintf(fp, "\t%s=%s (LPSTR)\n", pKey, val.u.pstrVal);
fprintf(fp, "\t%s=%d (DWORD)\n", pKey, val.u.ulVal);
Related Topics
count( )Count( ) and getNextKey( )GetNextKey( ) in the IValList Interface (deprecated) IGXValList interface
valInm_pValIn and valOutm_pValOut in the AppLogic class (deprecated)GXAppLogic class
execute( )Execute( ) in the AppLogic class (deprecated)GXAppLogic class
Copies a GXVAL object to the IValList IGXValList.
Syntax
public int setVal(
String pKey,
GXVAL pVal)
HRESULT SetVal(
LPSTR pKey,
GXVAL *pVal);
pKey. Key name of the GXVAL object to add to the IValList IGXValList.
pVal. The GXVAL object, identified by pKey, to add to the IValList IGXValList.
Usage
Use setVal( ) SetVal( ) to add an existing GXVAL object to the IValList IGXValList. If a GXVAL object with the same key name already exists, setVal( ) SetVal( ) overwrites it with the new one.
SetVal( ) makes a deep copy of the existing GXVAL object to add it to the IGXValList. If you do not want to make a deep copy, use SetValByRef( ) instead.
Rule
Do not add new GXVAL objects to the IValList IGXValList when iterating through the IValList IGXValList.
Tip
To add a new GXVAL object of type integer, string, or BLOB to the IValListIGXValList, use setValInt( )SetValInt( ), setValString( )SetValString( ), or setValBLOB( )SetValBLOB( ), respectively.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
// Returns the contents of the shopping basket
public 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
GXVAL struct
valInm_pValIn and valOutm_pValOut in the AppLogic class (deprecated)GXAppLogic class
execute( )Execute( ) in the AppLogic class (deprecated)GXAppLogic class
Adds a BLOB object to the IValListIGXValList.
Syntax
public int setValBLOB(
String pKey,
byte[] pBuff,
int nBuffLen)
HRESULT SetValBLOB(
LPSTR pKey,
LPBYTE pBuff,
ULONG nBuffLen);
pKey. Key name of the GXVAL object to add to the IValList IGXValList.
pBuff. The value of the BLOB object to add to the IValList IGXValList.
nBuffLen. Number of bytes to set for the byte array. The first nBuffLen bytes in the array pBuff hold the value.
Usage
Use setValBLOB( )SetValBLOB( ) to add a GXVAL object that contains a BLOB value to the IValListIGXValList. If a GXVAL object with the same key name already exists, setValBLOB( )SetValBLOB( ) overwrites it with the new one.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
getValBLOB( )GetValBLOB( )
getValBLOBSize( )GetValBLOBSize( )
Copies a GXVAL object to the IValList IGXValList.
Syntax
public int setValByRef(
String pKey,
GXVAL pVal)
HRESULT SetValByRef(
LPSTR pKey,
GXVAL *pVal);
pKey. Key name of the GXVAL object to add to the IValListIGXValList.
pVal. The GXVAL object, identified by pKey, to add to the IValListIGXValList.
Usage
Use setValByRef( )SetValByRef( ) to add an existing GXVAL object to the IGXValList. If a GXVAL object with the same key name already exists, setValByRef( )SetValByRef( ) overwrites it with the new one.
SetValByRef( ) makes a shallow copy of the existing GXVAL object to add it to the IGXValList. To make a deep copy, use SetVal( ).
Rule
Do not add new GXVAL objects to the IValListIGXValList when iterating through the IValListIGXValList.
Tip
To add a new GXVAL object of type integer, string, or BLOB to the IValListIGXValList, use setValInt( )SetValInt( ), setValString( )SetValString( ), or setValBLOB( )SetValBLOB( ), respectively.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
GXVAL struct
valInm_pValIn and valOutm_pValOut in the AppLogic class (deprecated)GXAppLogic class
execute( )Execute( ) in the AppLogic class (deprecated)GXAppLogic class
Adds a GXVAL object of type integer to the IValListIGXValList.
Syntax
public int setValInt(
String pKey,
int nVal)
HRESULT SetValInt(
LPSTR pKey,
LONG 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( )SetValInt( ) to add a GXVAL object of type integer to the IValListIGXValList. If a GXVAL object with the same key name already exists, setValInt( )SetValInt( ) overwrites it with the new one.
Rules
When iterating through existing GXVAL objects in the IValListIGXValList, do not add new GXVAL objects to the IValListIGXValList.
Tips
To add a new GXVAL object of type string or BLOB to the IValListIGXValList, use setValString( )SetValString( ) or setValBLOB( )SetValBLOB( ), respectively.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
// Specifies the User ID for the Session's IValList
public void setUserId(int uid, Agent agent)
getValList().setValInt("UserId", uid);
// Create an IGXValList and set integer values
IGXValList *pAcct1ValList=GXCreateValList();
pAcct1ValList->SetValInt(":balance", 0);
pAcct1ValList->SetValInt(":acctType", 1);
Related Topics
GXVAL struct
valInm_pValIn and valOutm_pValOut in the AppLogic class (deprecated)GXAppLogic class
execute( )Execute( ) in the AppLogic class (deprecated)GXAppLogic class
Adds a GXVAL object of type string to the IValListIGXValList.
Syntax
public int SetValString(
String pKey,
String val)
HRESULT SetValString(
LPSTR pKey,
LPSTR 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( )SetValString( ) to add a GXVAL object of type string to the IValListIGXValList. If a GXVAL object with the same key name already exists, setValString( )SetValString( ) overwrites it with the new one.
Rules
When iterating through existing GXVAL objects in the IValListIGXValList, do not add new GXVAL objects to the IValListIGXValList.
Tips
To add a new GXVAL object of type integer or BLOB to the IValListIGXValList, use setValInt( )SetValInt( ) or setValBLOB( )SetValBLOB( ), respectively.
Return Value
GXE.SUCCESS if the method succeeds.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
// Create and IValList and set string values
IValList custValList = GX.CreateValList();
custValList.setValString(":ssn", ssn);
custValList.setValString(":userName", userName);
// Create an IGXValList and set string values
IGXValList *pCustValList=GXCreateValList();
if(pUserValList&&pCustValList) {
pCustValList->SetValString(":ssn", m_pSsn);
pCustValList->SetValString(":firstName", m_pFirstName);
pCustValList->SetValString(":lastName", m_pLastName);
Related Topics
GXVAL struct
valInm_pValIn and valOutm_pValOut in the AppLogic class (deprecated)GXAppLogic class
execute( )Execute( ) in the AppLogic class (deprecated)GXAppLogic class
Previous Contents Index Next
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.
Last Updated November 25, 2002