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:


IGXBuffer interface

IGXSequence interface

IGXCallableStmt interface

IGXSequenceMgr interface

IGXColumn interface

IGXSession2 interface

IGXDataConn interface

IGXSessionIDGen interface

IGXDataConnSet interface

IGXState2 interface

IGXEnumObject interface

IGXStreamBuffer interface

IGXError interface

IGXTable interface

IGXHierQuery interface

IGXTemplateData interface

IGXHierResultSet interface

IGXTemplateMap interface

IGXLock interface

IGXTile interface

IGXMailBox interface

IGXTrans interface

IGXObject interface

IGXValList interface

IGXOrder interface





HttpServletRequest2 Interface  

IOrder Interface (deprecated)  

HttpSession2 Interface  

IPreparedQuery Interface (deprecated)  

IAppEvent Interface (deprecated)  

IQuery Interface (deprecated)  

IAppEventMgr Interface  

IResultSet Interface (deprecated)  

IAppEvent Interface (deprecated)  

IRowSet2 Interface  

IBuffer Interface (deprecated)  

ISequence Interface (deprecated)  

ICallableStmt Interface (deprecated)  

ISequenceMgr Interface (deprecated)  

ICallerContext Interface  

IServerContext Interface  

IColumn Interface (deprecated)  

IServletErrorHandler Interface  

IContext Interface  

ISession2 Interface (deprecated)  

IDataConn Interface (deprecated)  

ISessionIDGen Interface (deprecated)  

IDataConnSet Interface (deprecated)  

IState2 Interface  

IEnumObject Interface  

IStreamBuffer Interface (deprecated)  

IError Interface (deprecated)  

ITable Interface (deprecated)  

IHierQuery Interface (deprecated)  

ITemplateData Interface (deprecated)  

IHierResultSet Interface (deprecated)  

ITemplateMap Interface (deprecated)  

IListRowSet Interface  

ITile Interface (deprecated)  

ILock Interface  

ITrans Interface (deprecated)  

IMailbox Interface  

IValList Interface (deprecated)  

IContext Interface  

 



HttpServletRequest2 Interface

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


Methods


Table 3.1

Method

Description

convertITemplateDataToResultSet( )  

Creates a ResultSet wrapper for an ITemplateData object.  

dispatchAction( )  

Calls a method corresponding to a form-action in a servlet.  

formActionHandlerExists( )  

Determines whether the servlet has form-actions defined on it.  

getAppLogic( )  

Returns a handle to the AppLogic instance (ServletRunner) that served this request.  

getDefaultTemplate( )  

Retrieves the name of the file that handles output.  

getErrorCodes( )  

Retrieves a vector of error codes.  

getErrorMsgs( )  

Retrieves a vector of error messages.  

getErrorVars( )  

Retrieves a vector of error variables.  

getHttpSessionBean( )  

Retrieves an instance of a session object that is defined by the programmer.  

getServletErrorHandler( )  

Retrieves the object that handles validation errors.  

setDefaultTemplate( )  

Sets the default template to another file.  

setServletErrorHandler( )  

Sets the IServletErrorHandler that is used to process errors.  

validate( )  

Validates input parameters and session variables.  


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.


dispatchAction( )

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


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


getAppLogic( )

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.


Related Topics
AppLogic class


getDefaultTemplate( )

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


getErrorCodes( )

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:


Table 0.12

Data to Validate

Validation Rule

Description

Number  

VALIDATE_NUMBER  

Data is numerical.  

Integer  

VALIDATE_INTEGER  

Data is an integer.  

Positive integer  

VALIDATE_POSITIVE_INTEGER  

Data is a positive integer.  

Alphabetic  

VALIDATE_ALPHABETIC  

Data is alphabetic, a-z and/or A-Z.  

US phone number  

VALIDATE_US_PHONE  

Data consists only of 10 digits and optionally the characters (, ), and -.  

International phone number  

VALIDATE_INTL_PHONE  

Data consists only of numbers and the characters (, ), +, and -.  

Email  

VALIDATE_EMAIL  

Data is in the format a@b.c  

Social Security Number  

VALIDATE_SSN  

Data consists only of 9 digits and optionally the character -.  

Date  

VALIDATE_DATE  

Data is in the format "MM-DD-YY" or "MM-DD-YYYY". Month, day, and year are validated accordingly.  

Day  

VALIDATE_DAY  

Data is an integer between 1 and 31 inclusive.  

Month  

VALIDATE_MONTH  

Data is an integer between 1 and 12 inclusive.  

Year  

VALIDATE_YEAR  

Data is an integer between 1 and 99 inclusive, or between 1000 and 9999 inclusive.  

US zipcode  

VALIDATE_US_ZIPCODE  

Data consists of only 5 or 9 digits and optionally the character -.  


getErrorMsgs( )

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:


Table 0.13

Validation Rule

Error Message

VALIDATE_NUMBER  

Wrong number format!  

VALIDATE_INTEGER  

Wrong integer format!  

VALIDATE_POSITIVE_INTEGER  

Wrong positive integer format!  

VALIDATE_ALPHABETIC  

Wrong alphabetic format!  

VALIDATE_US_PHONE  

Wrong US phone format!  

VALIDATE_INTL_PHONE  

Wrong international phone format!  

VALIDATE_EMAIL  

Wrong email format!  

VALIDATE_SSN  

Wrong social security format!  

VALIDATE_DATE  

Wrong date format!  

VALIDATE_DAY  

Wrong day format!  

VALIDATE_MONTH  

Wrong month format!  

VALIDATE_YEAR  

Wrong year format!  

VALIDATE_US_ZIPCODE  

Wrong zip code format!  


getErrorVars( )

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.


getHttpSessionBean( )

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


getServletErrorHandler( )

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


setDefaultTemplate( )

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


setServletErrorHandler( )

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


validate( )

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( ):


Table 0.14

Error Type

Value

Error because data must be ...

ERROR_NUMBER  

5  

a number.  

ERROR_INTEGER  

6  

an integer.  

ERROR_POSITIVE_INTEGER  

7  

a positive integer.  

ERROR_ALPHABETIC  

8  

alphabetic characters (a-z, A-Z, or both).  

ERROR_US_PHONE  

9  

a phone number containing at most 10 digits and optional characters (, ), and -.  

ERROR_INTL_PHONE  

10  

a phone number containing only digits and optional characters, (, ), +, and -.  

ERROR_EMAIL  

11  

an address of the form a@b.c.  

ERROR_SSN  

12  

a Social Security Number containing 9 digits and an optional - character.  

ERROR_DATE  

13  

a date of the form MM-DD-YY or MM-DD-YYYY.  

ERROR_DAY  

14  

an integer between 1 and 31 inclusive.  

ERROR_MONTH  

15  

an integer between 1 and 12 inclusive.  

ERROR_YEAR  

16  

an integer between 1 and 99 inclusive or between 1000 and 9999 inclusive.  

ERROR_ZIP  

17  

a ZIP code containing either 5 digits or 9 digits, and an optional - character.  


Return Value
Returns true if the validation was successful; otherwise, returns false.


Related Topics
IServletErrorHandler interface



HttpSession2 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


Methods


Table 3.2

Method

Description

getBytes( )  

Returns the byte array defined by the specified name in the session.  

getInt( )  

Returns the integer defined by the specified name in the session.  

getString( )  

Returns the string defined by the specified name in the session.  

isAuthorized( )  

Checks whether the current user has a specified permission.  

loginSession( )  

Logs an authorized user into a session with a secured application.  

logoutSession( )  

Removes a user's association with a session.  

putBytes( )  

Defines a name in the session to have a specified byte array value.  

putInt( )  

Defines a name in the session to have a specified integer value.  

putString( )  

Defines a name in the session to have a specified String value.  


getBytes( )

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.


Related Topics
putBytes( )


getInt( )

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.


Related Topics
putInt( )


getString( )

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.


Related Topics
putString( )


isAuthorized( )

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


loginSession( )

Logs an authorized user into a session with a secured application.


Syntax
public abstract boolean loginSession(
   String user,
   String password)

user. The login user name.

password. The user 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( )


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


putBytes( )

Defines a name in the session to have a specified byte array value.


Syntax
public abstract void putBytes(
   String name,
   byte[] value)

name. The name to be defined.

value. The byte array value to assign to name.


Related Topics
getBytes( )


putInt( )

Defines a name in the session to have a specified integer value.


Syntax
public abstract void putInt(
   String name,
   int value)

name. The name to be defined.

value. The integer value to assign to name.


Related Topics
getInt( )


putString( )

Defines a name in the session to have a specified String value.


Syntax
public abstract void putString(
   String name,
   String value)

name. The name to be defined.

value. The String value to assign to name.


Related Topics
getString( )



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:

  • Run a specified AppLogic

  • Send an email
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


Methods


Table 3.3

Method

Description

deleteEvent( )DeleteEvent( )  

Removes a registered event from iPlanet Application Server.  

disableEvent( )DisableEvent( )  

Disables a registered event.  

enableEvent( )EnableEvent( )  

Enables a registered event.  

enumEvents( )EnumEvents( )  

Enumerates through the list of registered events.  

queryEvent( )QueryEvent( )  

Returns the properties of a registered event.  

registerEvent( )RegisterEvent( )  

Registers a named event for use in applications.  

setEvent( )SetEvent( )  

Triggers a registered event.  


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


    package GXApp.appevent;
    import java.lang.*;
    import java.util.*;
    import java.io.*;
    import com.kivasoft.*;
    import com.kivasoft.applogic.*;
    import com.kivasoft.util.*;
    import com.kivasoft.types.*;
    import com.kivasoft.appevent.*;

    public class ReportAgent extends AppLogic
    {
    static final java.lang.String eventName1 = "RepGenEvent";
    static final java.lang.String eventName2 = "ReportEvent";

    public int execute()
    {
    // Create IValLists to pass information
    // for appevent registration of the events
    IValList eventOutput;
    IValList eventInput1 = GX.CreateValList();
    IValList eventInput2 = GX.CreateValList();

    if ((eventInput1 == null) || (eventInput2 == null))
    return streamResult("Cannot create ValList<br>");

    // Get the appevent manager
    IAppEvent appEvent = getAppEvent();

    if (appEvent == null)
    return streamResult("Cannot get AppEvent<br>");

    // Add the RepGenAgent appevent name to the vallist
    eventInput1.setValString(GX_AE_RE_KEY_NAME.GX_AE_RE_KEY_NAME,
           eventName1);

    // Set the appevent state to be enabled
    eventInput1.setValInt(GX_AE_RE_KEY_STATE.GX_AE_RE_KEY_STATE,
           GX_AE_RE_ES_FLAG.GX_AE_RE_EVENT_ENABLED);

    // Set the appevent time to be 05:00:00 hrs everyday
    eventInput1.setValString(GX_AE_RE_KEY_TIME.GX_AE_RE_KEY_TIME,
           "5:0:0 */*/*");

    // Set the appevent action to run
    // the RepGenAgent applogic
    eventInput1.setValString(GX_AE_RE_KEY_NREQ.GX_AE_RE_KEY_NREQ,
       "GUIDGX-{620CB09B-1A1D-1315-AD23-0800207B918B}");

    // Register the event
    if (appEvent.registerEvent(eventName1, eventInput1) !=
             GXE.SUCCESS)
    return streamResult("Cannot register RepGenEvent<br>");

    // Add the ReportAgent appevent name to the vallist
    eventInput2.setValString(GX_AE_RE_KEY_NAME.GX_AE_RE_KEY_NAME,
           eventName2);

    // Set the appevent state to be enabled
    eventInput2.setValInt(GX_AE_RE_KEY_STATE.GX_AE_RE_KEY_STATE,
           GX_AE_RE_ES_FLAG.GX_AE_RE_EVENT_ENABLED);

    // Set the appevent time to be 06:00:00 hrs everyday
    eventInput2.setValString(GX_AE_RE_KEY_TIME.GX_AE_RE_KEY_TIME,
           "6:0:0 */*/*");

    // Set the appevent action to send e-mail
              eventInput2.setValString(GX_AE_RE_KEY_MTO.GX_AE_RE_KEY_MTO,
          "report@acme.com");

    // The content of the e-mail is in /tmp/report-file
    eventInput2.setValString(GX_AE_RE_KEY_MFILE.GX_AE_RE_KEY_
             MFILE, "/tmp/report-file");

    // The e-mail host running the SMTP server is mailsvr
    eventInput2.setValString(GX_AE_RE_KEY_MHOST.GX_AE_RE_KEY_
             MHOST, "mailsvr.acme.com");

    // The sender's e-mail address is admin@acme.com
    eventInput2.setValString(GX_AE_RE_KEY_SADDR.GX_AE_RE_KEY_
             SADDR, "admin@acme.com");

    // Register the event
    if (appEvent.registerEvent(eventName2, eventInput2) !=
             GXE.SUCCESS)
    return streamResult("Can not register ReportEvent<br>");
              return streamResult("Successfully Registered RepGenEvent and
                ReportEvent<br>");
    }
    }


    STDMETHODIMP
    ReportAgent::Execute()
    {
    HRESULT hr = NOERROR;
    IGXAppEvent *pAppEvent = NULL;
    IGXValList *pValList = NULL;
    LPSTR pReportEvName = "ReportEvent";
    LPSTR pRepGenEvName = "RepGenEvent";

    // Get a reference to the AppEvent Manager
    hr = GetAppEvent(&pAppEvent);
    if ((hr != NOERROR) || (pAppEvent == NULL))
    return StreamResult("AppEvent not found!<br>");

    // Create a vallist to pass information
    // for appevent registration of the first event
    pValList = GXCreateValList();
    if (pValList == NULL) {
    pAppEvent->Release();
    return Result(m_pValOut, "Can't create ValList<br>");
    }
    // Add the appevent name to the vallist
    GXSetValListString(pValList, GX_AE_RE_KEY_NAME, pRepGenEvName);

    // Set the appevent state to be enabled
    GXSetValListInt(pValList, GX_AE_RE_KEY_STATE,
       GX_AE_RE_EVENT_ENABLED);

    // Set the appevent time to be 05:00:00 hrs everyday
    GXSetValListString(pValList, GX_AE_RE_KEY_TIME, "5:0:0 */*/*");

    // Set the appevent action to run the RepGenAgent applogic
    GXSetValListString(pValList, GX_AE_RE_KEY_NREQ, "GUIDGX-{630CB09B-
       1A1D-1315-AD23-0800207B918B}");

    // Register the appevent
    hr = pAppEvent->RegisterEvent(pRepGenEvName, pValList);
    pValList->Release();

    // Create a vallist to pass information
    // for appevent registration of the second event
    //
    pValList = GXCreateValList();
    if (pValList == NULL) {
    pAppEvent->Release();
    return Result(m_pValOut, "Can't create ValList<br>");
    }
    // Add the appevent name to the vallist
    GXSetValListString(pValList, GX_AE_RE_KEY_NAME, pReportEvName);

    // Set the appevent state to be enabled
    GXSetValListInt(pValList, GX_AE_RE_KEY_STATE,
       GX_AE_RE_EVENT_ENABLED);

    // Set the appevent time to be 06:00:00 hrs everyday
    GXSetValListString(pValList, GX_AE_RE_KEY_TIME, "6:0:0 */*/*");

    // Set the appevent action to send
    // e-mail to report@acme.com
    GXSetValListString(pValList, GX_AE_RE_KEY_MTO, "report@acme.com");

    // The content of the e-mail is in /tmp/report-file
    GXSetValListString(pValList, GX_AE_RE_KEY_MFILE, "/tmp/report-
       file");

    // The e-mail host running the SMTP server is mailsvr
    GXSetValListString(pValList, GX_AE_RE_KEY_MHOST, "mailsvr");

    // The sender's e-mail address is admin@acme.com
    GXSetValListString(pValList, GX_AE_RE_KEY_SADDR, "admin@acme.com");

    // Register the appevent
    hr = pAppEvent->RegisterEvent(pReportEvName, pValList);

    // Clean-up resources and return
    //
    pValList->Release();
    pAppEvent->Release();
    return StreamResult("Successfully Registered RepGenEvent and
       ReportEvent<br>");
    }


Related Topics

getAppEvent( )GetAppEvent( ) method in the AppLogicGXAppLogic class

IAppEventMgr InterfaceIGXAppEventMgr interface

IAppEvent Interface (deprecated)IGXAppEventObj interface

IValList interfaceIGXValList interface

"Using Events"


deleteEvent( )


DeleteEvent( )

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


disableEvent( )


DisableEvent( )

Disables a registered event.


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

enableEvent( )EnableEvent( )

registerEvent( )RegisterEvent( )


enableEvent( )


EnableEvent( )

Enables a registered event.


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


enumEvents( )


EnumEvents( )

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:


// Open /tmp/report-file for writing the report
FileOutputStream outFile = null;
try {
outFile = new FileOutputStream("/tmp/report-file");
} catch (IOException e) {
}
if (outFile == null)
return streamResult("Can not open /tmp/report-file<br>");

ObjectOutputStream p = null;
try {
p = new ObjectOutputStream(outFile);
} catch (IOException e) {
}
if (p == null)
return streamResult("Cannot create ObjectOutputStream<br>");

// get appevent manager
IAppEvent appEvent = getAppEvent();

// Get the Enumeration object for all registered appevents
IEnumObject enumObj = appEvent.enumEvents();

// Retrieve the count of registered appevents
int count = enumObj.enumCount();
try {
p.writeObject("Number of Registered Events: ");
p.writeInt(count);
} catch (IOException e) {
return streamResult("Failed to write to report file<br>");
}

enumObj.enumReset(0);

while (count > 0) {
IObject vListObj = enumObj.enumNext();
if (vListObj instanceof IValList) {
IValList vList = (IValList)vListObj;

String name =
             vList.getValString(GX_AE_RE_KEY_NAME.GX_AE_RE_KEY_NAME);
try {
p.writeObject("\nDefinitions for AppEvent: ");
p.writeObject(name);
p.writeObject("\n");
} catch (IOException e) {
return streamResult("Failed to write to report file<br>");
}

// Reset the next GXVAL to retrieve
// from ValList to be the first one
vList.resetPosition();

// Iterate through all the GXVALs in the vallist
// and print them


HRESULT hr = NOERROR;
IGXEnumObject *pEObjs = NULL;
IGXAppEvent *pAppEvent = NULL;
IGXValList *pValList = NULL;
CHAR pBuf[128];
ULONG ulCount = 0;
FILE *fp;

// Open /tmp/report-file for writing the report
fp = fopen("/tmp/report-file", "w");

// Get a reference to the AppEvent Manager
hr = GetAppEvent(&pAppEvent);

// Get the Enumeration object for all registered appevents
hr = pAppEvent->EnumEvents(&pEObjs);

// Retrieve the count of registered appevents
hr = pEObjs->EnumCount(&ulCount);

fprintf(fp, "Number of Registered Events: %d\n", ulCount);

// Reset the next enumeration object to be the first instance
hr = pEObjs->EnumReset(0);

// Iterate through all the enumeration instances
while (ulCount--) {
CHAR pKey[256];
GXVAL val;

// Get the next instance
hr = pEObjs->EnumNext((IGXObject **)&pValList);

// Retrieve and print the name of the appevent
pValList->GetValByRef(GX_AE_RE_KEY_NAME, &val);
fprintf(fp, "\nDefinitions for AppEvent named %s\n", val.u.pstrVal);

// Reset to the first GXVAL in the ValList
pValList->ResetPosition();

// 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);
else
fprintf(fp, "\t%s=%d (DWORD)\n", pKey, val.u.ulVal);
}
pValList->Release();
}
// Save the file
fclose(fp);

// Release all resources used and return
pEObjs->Release();
pAppEvent->Release();
return StreamResult("Successfully generated report<br>");


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


queryEvent( )


QueryEvent( )

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


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:


Table 3.4

Key

Value

GX_AE_RE_KEY_NAME. GX_AE_RE_KEY_NAME  

A string representing the name of the event. If specified, the name must be the same one specified as the pEventName parameter.  

GX_AE_RE_KEY_STATE. GX_AE_RE_KEY_STATE  

A variableAn enum that specifies the initial state of the event:

GX_AE_RE_ES_FLAG.GX_AE_RE_EVENT_
DISABLED

GX_AE_RE_ES_FLAG.GX_AE_RE_EVENT_
ENABLED

GX_AE_RE_EVENT_DISABLED

GX_AE_RE_EVENT_ENABLED  

GX_AE_RE_KEY_TIME. GX_AE_RE_KEY_TIME  

The time at which the event will be triggered. Use the following format:

hh:mm:ss W/DD/MM

hh: 0 -23

mm: 0 - 59

ss: 0 - 59

W (day of the week): 0 - 6 with 0 = Sunday.

DD (day of the month): 1 - 31

MM (month): 1 - 12

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 *.  

GX_AE_RE_KEY_NREQ. GX_AE_RE_KEY_NREQ  

The AppLogic to execute when the event is triggered. Use the following format:

GUIDGX-{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX?Param1=ABC&Param2=123  

GX_AE_RE_KEY_MFILE. GX_AE_RE_KEY_MFILE*  

The name of the file that contains the body of an email message.  

GX_AE_RE_KEY_MTO. GX_AE_RE_KEY_MTO*  

A comma separated list of users to send the email to.  

GX_AE_RE_KEY_MHOST. GX_AE_RE_KEY_MHOST*  

The name of the SMTP mail server.  

GX_AE_RE_KEY_SADDR. GX_AE_RE_KEY_SADDR*  

The sender's email address.  

* 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:


static final java.lang.String eventName1 = "RepGenEvent";

// Get the appevent manager
IAppEvent appEvent = getAppEvent();

// Create IValList to pass information for
// registration of an event
IValList eventInput1 = GX.CreateValList();

// Add the RepGenAgent appevent name to the vallist
eventInput1.setValString(GX_AE_RE_KEY_NAME.GX_AE_RE_KEY_NAME, eventName1);

// Set the appevent state to be enabled
eventInput1.setValInt(GX_AE_RE_KEY_STATE.GX_AE_RE_KEY_STATE, GX_AE_RE_ES_FLAG.GX_AE_RE_EVENT_ENABLED);

// Set the appevent time to be 05:00:00 hrs everyday
eventInput1.setValString(GX_AE_RE_KEY_TIME.GX_AE_RE_KEY_TIME, "5:0:0 */*/*");

// Set the appevent action to run an AppLogic
eventInput1.setValString(GX_AE_RE_KEY_NREQ.GX_AE_RE_KEY_NREQ, "GUIDGX-{620CB09B-1A1D-1315-AD23-0800207B918B}");

// Register the event
if (appEvent.registerEvent(eventName1, eventInput1) != GXE.SUCCESS)
return streamResult("Cannot register RepGenEvent<br>");


HRESULT hr = NOERROR;
IGXAppEvent *pAppEvent = NULL;
IGXValList *pValList = NULL;
LPSTR pReportEvName = "ReportEvent";
LPSTR pRepGenEvName = "RepGenEvent";

// Get a reference to the AppEvent Manager
hr = GetAppEvent(&pAppEvent);
if ((hr != NOERROR) || (pAppEvent == NULL))
return StreamResult("AppEvent not found!<br>");

// Create a vallist to pass information
// for appevent registration of the first event
pValList = GXCreateValList();
if (pValList == NULL) {
pAppEvent->Release();
return Result(m_pValOut, "Can't create ValList<br>");
}
// Add the appevent name to the vallist
GXSetValListString(pValList, GX_AE_RE_KEY_NAME, pRepGenEvName);

// Set the appevent state to be enabled
GXSetValListInt(pValList, GX_AE_RE_KEY_STATE, GX_AE_RE_EVENT_ENABLED);

// Set the appevent time to be 05:00:00 hrs everyday
GXSetValListString(pValList, GX_AE_RE_KEY_TIME, "5:0:0 */*/*");

// Set the appevent action to run the RepGenAgent applogic
GXSetValListString(pValList, GX_AE_RE_KEY_NREQ, "GUIDGX-{630CB09B-1A1D-1315-AD23-0800207B918B}");

// Register the appevent
hr = pAppEvent->RegisterEvent(pRepGenEvName, pValList);
pValList->Release();


Related Topics
enableEvent( )EnableEvent( )

setEvent( )SetEvent( )

getAppEvent( )GetAppEvent( ) method in the AppLogicGXAppLogic class

IValList interfaceIGXValList interface


setEvent( )


SetEvent( )

Triggers a registered event.


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:


Table 3.5

Key

Value

GX_AE_RE_KEY_NAME. GX_AE_RE_KEY_NAME  

A string representing the name of the event. If specified, the name must be the same one specified as the pEventName parameter.  

GX_AE_RE_KEY_STATE. GX_AE_RE_KEY_STATE  

A variableAn enum that specifies the initial state of the event:

GX_AE_RE_ES_FLAG.GX_AE_RE_EVENT_DISABLED

GX_AE_RE_ES_FLAG.GX_AE_RE_EVENT_ENABLED  

GX_AE_RE_KEY_TIME. GX_AE_RE_KEY_TIME  

The time at which the event will be triggered. Use the following format:

hh:mm:ss W/DD/MM

hh: 0 -23

mm: 0 - 59

ss: 0 - 59

W (day of the week): 0 - 6 with 0 = Sunday.

DD (day of the month): 1 - 31

MM (month): 1 - 12

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 *.  

GX_AE_RE_KEY_NREQ. GX_AE_RE_KEY_NREQ  

The AppLogic to execute when the event is triggered. Use the following format:

GUIDGX-{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX?Param1=ABC&Param2=123  

GX_AE_RE_KEY_MFILE. GX_AE_RE_KEY_MFILE*  

The name of the file that contains the body of an email message.  

GX_AE_RE_KEY_MTO. GX_AE_RE_KEY_MTO*  

A comma separated list of users to send the email to.  

GX_AE_RE_KEY_MHOST. GX_AE_RE_KEY_MHOST*  

The name of the SMTP mail server.  

GX_AE_RE_KEY_SADDR. GX_AE_RE_KEY_SADDR*  

The sender's email address.  

* 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



IAppEventMgr Interface



IGXAppEventMgr 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:

    • executes a specified servlet.

    • executes a specified AppLogic.

    • sends an email message.

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


Methods


Table 3.6

Method

Description

createEvent( )CreateEvent( )  

Creates an empty application event object.  

deleteEvent( )DeleteEvent( )  

Removes a registered event from iPlanet Application Server.  

disableEvent( )DisableEvent( )  

Disables a registered event.  

enableEvent( )EnableEvent( )  

Enables a registered event.  

enumEvents( )EnumEvents( )  

Enumerates through the list of registered events.  

queryEvent( )GetEvent( )  

Retrieves the IAppEventObjIGXAppEventObj for a registered event.  

registerEvent( )RegisterEvent( )  

Registers a named event for use in applications.  

setEvent( )TriggerEvent( )  

Triggers a registered event.  


Related Topics

GetAppEventMgr( ) in the GXContext classGXContextGetAppEventMgr( ),
IValList Interface (deprecated)IGXAppEventMgr interface,
IAppEvent Interface (deprecated)IGXAppEventObj interface

"Using Events"


createEvent( )


CreateEvent( )

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


deleteEvent( )


DeleteEvent( )

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


disableEvent( )


DisableEvent( )

Disables a registered event.


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

enableEvent( )EnableEvent( )

registerEvent( )RegisterEvent( )


enableEvent( )


EnableEvent( )

Enables a registered event.


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


enumEvents( )


EnumEvents( )

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:



// Open /tmp/report-file for writing the report
FileOutputStream outFile = null;
try {
outFile = new FileOutputStream("/tmp/report-file");
} catch (IOException e) {
}
if (outFile == null)
return streamResult("Can not open /tmp/report-file<br>");

ObjectOutputStream p = null;
try {
p = new ObjectOutputStream(outFile);
} catch (IOException e) {
}
if (p == null)
return streamResult("Cannot create ObjectOutputStream<br>");

// get appevent manager
IAppEventMgr appEventMgr = GetAppEventMgr();

// Get the Enumeration object for all registered appevents
IEnumObject enumObj = appEventMgr.enumEvents();

// Retrieve the count of registered appevents
int count = enumObj.enumCount();
try {
p.writeObject("Number of Registered Events: ");
p.writeInt(count);
} catch (IOException e) {
return streamResult("Failed to write to report file<br>");
}

enumObj.enumReset(0);

IObject eventObj = enumObj.enumNext();
while ((eventObj = enumObj.enumNext()) != null) {
if (eventObj instanceof IAppEventObj) {
IAppEventObj appEventObj = (IAppEventObj)eventObj;

// print each appEvent

// get the name of the appevent
String name = appEventObj.getName();
try {
p.writeObject("\nDefinitions for AppEvent: ");
p.writeObject(name);
p.writeObject("\n");
} catch (IOException e) {
return streamResult("Failed to write to report file<br>");
}

// print the attributes..
IValList attrs = appEventObj.getAttributes();
attrs.resetPosition();
// Iterate through all the GXVALs in the attr s valllist
// and print them
...
...
...

// enumerate through the actions
enumActions = appEventObj.enumActions();

// Retrieve the count of registered actions for this event
count = enumActions.enumCount();
try {
p.writeObject("Number of Actions: ");
p.writeInt(count);
} catch (IOException e) {
return streamResult("Failed to write ActionCount to report file");
}

enumActions.enumReset(0);
IObject obj ;
while ((obj = enumActions.enumNext()) != null) {
// print each action
if (obj instanceof IValList) {
IValList action = (IValList)obj;

action.resetPosition();
// Iterate through all the GXVALs in the vallist
// and print them
...
...
...
}
}
}
}



HRESULT hr = NOERROR;
IGXEnumObject *pEObjs = NULL;
IGXAppEventMgr *pAppEventMgr = NULL;
CHAR pBuf[128];
ULONG ulCount = 0;
FILE *fp;

// Open /tmp/report-file for writing the report
fp = fopen("/tmp/report-file", "w");

// Get a reference to the AppEvent Manager
hr = GXContextGetAppEventMgr(m_context, &pAppEventMgr);

// Get the Enumeration object for all registered appevents
hr = pAppEventMgr->EnumEvents(&pEObjs);

// Retrieve the count of registered appevents
hr = pEObjs->EnumCount(&ulCount);
fprintf(fp, "Number of Registered Events: %d\n", ulCount);

// Reset the next enumeration object to the first instance
hr = pEObjs->EnumReset(0);

// Iterate through all the enumeration instances
while (ulCount--) {
CHAR pKey[256];
CHAR name[256];
GXVAL val;
IGXValList *pValList = NULL;
IGXAppEventObj *pAppEventObj = NULL;

// Get the next instance
hr = pEObjs->EnumNext((IGXObject **)&pAppEventObj);

// Retrieve and print the name of the appevent
hr = pAppEventObj->GetName(name, 256);
fprintf(fp, "\nDefinitions for AppEvent named %s\n", name);

// Retrieve attributes
hr = pAppEventObj->GetAttributes(&pValList);

// Reset to the first GXVAL in the ValList
pValList->ResetPosition();

fprintf(fp, "\nAttributes for AppEvent\n");
// 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);
else
fprintf(fp, "\t%s=%d (DWORD)\n", pKey, val.u.ulVal);
}
pValList->Release();

// Retrieve and print Actions
fprintf(fp, "\nActions for AppEvent\n");
hr = pAppEventObj->EnumActions(&pEActionObjs);

// Retrieve the count of registered appevents
hr = pEActionObjs->EnumCount(&ulActionCount);
fprintf(fp, "Number of Actions for event: %d\n", ulActionCount);

// Reset the next enumeration object to be the first instance
hr = pEActionObjs->EnumReset(0);

// Iterate through all the enumeration instances
while (ulActionCount--) {
// Get the next action
hr = pEActionObjs->EnumNext((IGXObject **)&pValList);

// Reset to the first GXVAL in the ValList
pValList->ResetPosition();

// Iterate through all the GXVALs that describe the action
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);
else
fprintf(fp, "\t%s=%d (DWORD)\n", pKey, val.u.ulVal);
}
pValList->Release();
}

pEActionObjs->Release();
pAppEventObj->Release();
}

// Save the file
fclose(fp);

// Release all resources used and return
pEObjs->Release();
pAppEventMgr->Release();
return StreamResult("Successfully generated report<br>");


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


getEvent( )


GetEvent( )

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


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:



static final java.lang.String eventName1 = "RepGenEvent";

// get the appevent manager
IAppEventMgr appEventMgr = GXContext.GetAppEventMgr(context);

// create a appevent object
IAppEventObj appEventObj = appEventMgr.createEvent(eventName1);

// create ValList for attributes.
IValList attrs = GX.CreateValList();

// set the Action Mode to Serial for serial-execution of actions.
attrs.setValInt(GXConstants.GX_AE2_RE_KEY_ACTION_MODE,
GX_AE2_RE_SA_FLAG.GX_AE2_RE_ACTION_SERIAL);

// set the appevent time to be 05:00:00 hrs everyday
attrs.setValString(GXConstants.GX_AE2_RE_KEY_TIME, "5:0:0 */*/*");

// set the attributes
appEventObj.setAttributes(attrs);

// create ValLists for actions (2 applogic newrequest and 2 servlet).
IValList action1 = GX.CreateValList();
IValList action2 = GX.CreateValList();
IValList action3 = GX.CreateValList();
IValList action4 = GX.CreateValList();

// set action1 to run an appLogic
action1.setValString(GXConstants.GX_AE2_RE_KEY_NREQ,
"GUIDGX-{620CB09B-1A1D-1315-AD23-0800207B918B}");

// set action1 to run another appLogic
action2.setValString(GXConstants.GX_AE2_RE_KEY_NREQ,
"GUIDGX-{60A36CC0-9F69-11D2-9907-0060973797BF}");

// set action2 to run a servlet
action3.setValString(GXConstants.GX_AE2_RE_KEY_SERVLET,
"TxReportServlet");

// set action3 to run another servlet
action4.setValString(GXConstants.GX_AE2_RE_KEY_SERVLET,
"SummaryReportServlet");

// add actions in the order we want them to be executed
appEventObj.addAction(action1);
appEventObj.addAction(action2);
appEventObj.addAction(action3);
appEventObj.addAction(action4);

// Register the event
if (appEventMgr.registerEvent(eventName1, appEventObj) != GXE.SUCCESS)
return streamResult("Cannot register RepGenEvent<br>");


HRESULT hr = NOERROR;
IGXAppEventMgr *pAppEventMgr = NULL;
IGXValList *pValList = NULL;

LPSTR pRepGenEvName = "RepGenEvent";

// Get a reference to the AppEvent Manager
hr = GXContextGetAppEventMgr(m_context, &pAppEvent);

if ((hr != NOERROR) || (pAppEventMgr == NULL))
return StreamResult("AppEventMgr not found!<br>");

// Create an empty Event Object
hr = pAppEventMgr->CreateEvent(pRepGenEvName, &pAppEventObj);
if ((hr != NOERROR) || (pAppEventObj == NULL))
return StreamResult("CreateEvent failed!<br>");

// Prepare and set the Attributes.
// Create a vallist for the Attributes
pValList = GXCreateValList();

// Set the appevent time to be 05:00:00 hrs everyday
GXSetValListString(pValList, GX_AE2_RE_KEY_TIME, "5:0:0 */*/*");

// Set the attributes
hr = pAppEventObj->SetAttributes(pValList);
if (hr != NOERROR)
return StreamResult("Can't set Attributes<br>");

pValList->Release();

// Add 4 Actions in the order we want them to be executed

// Set action 1 to run the SummaryRepGenAgent1 applogic
pValList = GXCreateValList();
GXSetValListString(pValList, GX_AE2_RE_KEY_NREQ,
"GUIDGX-{630CB09B-1A1D-1315-AD23-0800207B918B}");
hr = pAppEventObj->AddAction(pValList);
pValList->Release();

// Set action 2 to run the SummaryRepGenAgent2 applogic
pValList = GXCreateValList();
GXSetValListString(pValList, GX_AE2_RE_KEY_NREQ,
"GUIDGX-{414643FA-B74A-1544-C25E-0800207B8777}");
hr = pAppEventObj->AddAction(pValList);
pValList->Release();

// Set action 3 to run the DetailRepGenServlet1 servlet
pValList = GXCreateValList();
GXSetValListString(pValList, GX_AE2_RE_KEY_SERVLET,
"DetailRepGenServlet1");
hr = pAppEventObj->AddAction(pValList);
pValList->Release();

// Set action 4 to run the DetailRepGenServlet2 servlet
pValList = GXCreateValList();
GXSetValListString(pValList, GX_AE2_RE_KEY_SERVLET,
"DetailRepGenServlet2");
hr = pAppEventObj->AddAction(pValList);
pValList->Release();

// Register the appevent
hr = pAppEventMgr->RegisterEvent(pAppEventObj);

pAppEventObj->Release();
pAppEventMgr->Release();


Related Topics
enableEvent( )EnableEvent( )

setEvent( )TriggerEvent( )


triggerEvent( )


TriggerEvent( )

Triggers a registered event.


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.


Table 0.15

If the action is ...

Then pValList is ...

an AppLogic.  

passed as input to that AppLogic.  

an email message.  

simply ignored.  

a servlet.  

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



IAppEventObj Interface



IGXAppEventObj interface

See the IAppEventMgrIGXAppEventMgr interface for details on IAppEventObjIGXAppEventObj.


Package Include File

com.kivasoftgxiappevent.h


Methods


Table 3.7

Method

Description

addAction( )AddAction( )  

Appends an action to an ordered list of actions.  

deleteActions( )DeleteActions( )  

Deletes all actions added to this IGXAppEventObj.  

enumActions( )EnumActions( )  

Enumerates the actions added to this IGXAppEventObj.  

getAttributes( )GetAttributes( )  

Retrieves the list of attributes of an IGXAppEventObj.  

getName( )GetName( )  

Retrieves the name of the IGXAppEventObj.  

setAttributes( )SetAttributes( )  

Sets a list of attribute values for the IGXAppEventObj.  


Related Topics

IAppEventMgrIGXAppEventMgr interface


addAction( )


AddAction( )

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.

For AppLogics:


Table 3.8

Key

Value

GXConstants.GX_AE2_RE_KEY_NREQ  

The AppLogic to execute when the event is triggered. Use the following format:

GUIDGX-{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX?Param1=ABC&Param2=123. The parameters and their values are passed as input to the events.  

For email:

To send email when the event is triggered, all of the following items must be specified.


Table 3.9

Key

Value

GXConstants. GX_AE2_RE_KEY_MFILE  

The name of the file that contains the body of an email message.  

GXConstants. GX_AE2_RE_KEY_MTO  

A comma separated list of users to send the email to.  

GXConstants. GX_AE2_RE_KEY_MHOST  

The name of the SMTP mail server.  

GXConstants. GX_AE2_RE_KEY_SADDR  

The sender's email address.  

For servlets:


Table 3.10

Key

Value

GXConstants. GX_AE2_RE_KEY_SERVLET  

The name of the servlet to be executed when the event is triggered. Use the following format:

appName/ServletName?Param1=ABC&Param2=123. Parameters and their values are passed as input to the events. The only required item is the servlet name. The application name and parameters are optional.  


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.


deleteActions( )


DeleteActions( )

Deletes all actions added to this IGXAppEventObj.


Syntax
public int deleteActions()

HRESULT 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.


enumActions( )


EnumActions( )

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.


getAttributes( )


GetAttributes( )

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


getName( )


GetName( )

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.


setAttributes( )


SetAttributes( )

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_EVENT_DISABLED

    • GXConstants.GX_AE2_RE_EVENT_ENABLED (the default)

  • GXConstants.GX_AE2_RE_KEY_TIME
    An optional key that specifies the time at which the event will be triggered. Use the following format:

    • hh:mm:ss W/DD/MM

    • hh: 0 -23

    • mm: 0 - 59

    • ss: 0 - 59

    • W (day of the week): 0 - 6 with 0 = Sunday.

    • DD (day of the month): 1 - 31

    • MM (month): 1 - 12
    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:

    • GXConstants.GX_AE2_RE_ACTION_SERIAL

    • GXConstants.GX_AE2_RE_ACTION_CONCURRENT (the default)

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.



IGXBuffer interface

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


Methods


Table 3.11

Method

Description

alloc( )Alloc( )  

Specifies the size of the memory block, in bytes.  

getAddress( )GetAddress( )  

Returns a copy of the buffer contents.Returns the address of the memory block.  

getSize( )GetSize( )  

Returns the size of the memory block, in bytes.  

setData( )SetData( )  

Copies data to a memory block.  


alloc( )


Alloc( )

Specifies the size of the memory block, in bytes.


Syntax
public int alloc(
   int nSize)

HRESULT Alloc(
   ULONG 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( ).


Rules

  • 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.


Example


String str = "Hello World";
byte tmp[] = new byte[12];
str.getBytes(0, 11, tmp, 0);

IBuffer buff;

buff = GX.CreateBuffer();
buff.alloc(128);
buff.setData(tmp, 12);

// The following example is an alternate to the
// previous one. It uses GX.CreateBufferFromString()
// instead of GX.CreateBuffer().

IBuffer buff;
buff = GX.CreateBufferFromString("Hello World");


LPSTR str = "Hello World";
IGXBuffer buff;
buff = GXCreateBuffer();
buff->Alloc(128);
buff->SetData((LPBYTE) str, 12);


Related Topics
getAddress( )GetAddress( )


getAddress( )


GetAddress( )

Returns a copy of the buffer contents.

Returns the address of the memory block.


Syntax
public byte[] getAddress()

LPBYTE 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.

HRESULT hr;

IGXBuffer *buff;

buff = NULL;

hr = query->GetTables(&buff);

if (hr == NOERROR && buff)

{

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

StreamResult(".<br>");

// Release buff when done with it.

//

buff->Release();

}


Related Topics
alloc( )Alloc( )


getSize( )


GetSize( )

Returns the size of the memory block, in bytes.


Syntax
public int getSize()

ULONG GetSize();


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

setData( )SetData( )


setData( )


SetData( )

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.


Example


String str = "Hello World";
byte tmp[] = new byte[12];
str.getBytes(0, 11, tmp, 0);

IBuffer buff;

buff = GX.CreateBuffer();
buff.alloc(128);
buff.setData(tmp, 12);

table.setValPieceByOrd(1, buff, 12);


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

getSize( )GetSize( )



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.



IGXCallableStmt interface

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


Methods


Table 3.12

Method

Description

close( )Close( )  

Releases the callable statement.  

execute( )Execute( )  

Executes the stored procedure called by the ICallableStatementIGXCallableStatement object.  

executeMultipleRS( )ExecuteMultipleRS( )  

Executes a stored procedure, called by the ICallableStmtIGXCallableStmt object, that can return multiple result sets.  

getMoreResults( )GetMoreResults( )  

Checks if there is a result set to retrieve. This method is valid only if you used executeMultipleRS( )ExecuteMultipleRS( ), not execute( )Execute( ), to execute a stored procedure called by the ICallableStmtIGXCallableStmt object.  

getParams( )GetParams( )  

Returns the value of the stored procedure's output parameter or parameters.  

getResultSet( )GetResultSet( )  

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.  

setParams( )SetParams( )  

Specifies the parameter values to pass to the stored procedure.  


Related Topics

prepareCall( )PrepareCall( ) in the IDataConn Interface (deprecated)IGXDataConn interface

"Using Stored Procedures"


close( )


Close( )

Releases the callable statement.


Syntax
public int close()

HRESULT Close()


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.


execute( )


Execute( )

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

flags dwFlags.

  • 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, &param1. 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.


Example


//Write command to call stored procedure
String theProc = "{call myProc1(&p1, :p2)}";
IQuery myquery;
myquery = createQuery();
myquery.setSQL(theProc);

//Prepare the callable statement for execution
ICallableStmt myStmt;
myStmt = conn_rtest.prepareCall(0, myquery, null, null);

//Set the in parameter value
IValList inParams = GX.CreateValList();
inParams.setValInt("&p1",6210603);
//Set the out parameter value to any integer
inParams.setValInt(":p2", 0);

//Run the callable statement
myStmt.execute(0, inParams, null, null);

//Get the stored procedure's output value
outParams = myStmt.getParams(0);


// Write the command to call the stored procedure
IGXQuery *qry = NULL;
hr = CreateQuery(&qry);
if (hr == NOERROR &&
qry)
{
qry->SetSQL("{:ret = call myFunction(&param1)}");

//Prepare the callable statement for execution
IGXCallableStmt *s = NULL;
hr = conn->PrepareCall(0, qry, NULL, NULL, &s);
if (hr == NOERROR &&
s)
{
// Set the in parameter values
IGXValList *params;
params = GXCreateValList();
params->SetValInt(":ret", 9999);
params->SetValInt("&param1", 20);

IGXResultSet *rs = NULL;

// Run the callable statement
hr = s->Execute(0, params, NULL, NULL, &rs);
if (hr == NOERROR &&
rs)
{
// Get the stored procedure's output value
IGXValList *paramsOut = NULL;
hr = s->GetParams(0, &paramsOut);
if (hr == NOERROR &&
paramsOut)
{


Related Topics
prepareCall( )PrepareCall( ) in the IDataConn Interface (deprecated)IGXDataConn interface

getParams( )GetParams( )

setParams( )SetParams( )

"Using Stored Procedures"


executeMultipleRS( )


ExecuteMultipleRS( )

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)

dwFlags.

Specify 0.

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, &param1. 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.


Example


//Write command to call stored procedure
String proccall = "{call multiRSproc()}";
IQuery qryobj = GX.createQuery();
qryobj.setSQL(proccall);

//Prepare the callable statement for execution
ICallableStmt stmt = connobj.PrepareCall(0, qryobj, null, null);

//Create the IValList to pass to the stored procedure
IValList inparms = GX.CreateValList();

//Run the callable statement
stmt.executeMultipleRS(0, inparms, null, null);

//Check if there is a result set
if (stmt.getMoreResults())
{
//Get the result set
IResultSet rsobj = stmt.getResultSet();
while (rsobj.fetchNext()) {
if (rsobj.getValueInt(1) == 100) {
System.out.println("Found record 100");
}
}
}
//Check if there is another result set
if (stmt.getMoreResults()) {
rsobj = stmt.getResultSet();
while (rsobj.fetchNext()) {
if (rsobj.getValueString(2) == 'George') {
System.out.println("Found record George");
}
}
}


hr = stmt->ExecuteMultipleRS(0, params, NULL, NULL);
DWORD moreResult = TRUE;
do {
hr = stmt->GetMoreResults(&moreResult);
if (moreResult == FALSE)
{
StreamResult("No more Results to process<BR>");
break;
}
else
{
IGXResultSet *pResultSet;
hr = stmt->GetResultSet(&pResultSet);
if (pResultSet)
{
DisplayResult(pResultSet);
pResultSet->Release();
}
}
} while(TRUE);


Related Topics
prepareCall( )PrepareCall( ) in the IDataConn Interface (deprecated)IGXDataConn interface

getMoreResults( )GetMoreResults( )

getResultSet( )GetResultSet( )

"Using Stored Procedures"


getMoreResults( )


GetMoreResults( )

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.


Example


//Run the callable statement
stmt.executeMultipleRS(0, inparms, null, null);

//Check if there is a result set
if (stmt.getMoreResults())
{
//Get the result set
IResultSet rsobj = stmt.getResultSet();
while (rsobj.fetchNext()) {
if (rsobj.getValueInt(1) == 100) {
System.out.println("Found record 100");
}
}
}
//Check if there is another result set
if (stmt.getMoreResults()) {
rsobj = stmt.getResultSet();
while (rsobj.fetchNext()) {
if (rsobj.getValueString(2) == 'George') {
System.out.println("Found record George");
}
}
}


hr = stmt->ExecuteMultipleRS(0, params, NULL, NULL);
DWORD moreResult = TRUE;
do {
hr = stmt->GetMoreResults(&moreResult);
if (moreResult == FALSE)
{
StreamResult("No more Results to process<BR>");
break;
}
else
{
IGXResultSet *pResultSet;
hr = stmt->GetResultSet(&pResultSet);
if (pResultSet)
{
DisplayResult(pResultSet);
pResultSet->Release();
}
}
} while(TRUE);


Related Topics
prepareCall( )PrepareCall( ) in the IDataConn Interface (deprecated)IGXDataConn interface

executeMultipleRS( )ExecuteMultipleRS( )

getResultSet( )GetResultSet( )

"Using Stored Procedures"


getParams( )


GetParams( )

Returns the value of the stored procedure's output parameter or parameters.


Syntax
public IValList getParams(
   int dwFlags);

HRESULT GetParams(
   DWORD dwFlags
   IGXValList **ppParams);

dwFlags. Specify 0 (zero).

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.


Example


// Write the command to call the stored procedure
IGXQuery *qry = NULL;
hr = CreateQuery(&qry);
if (hr == NOERROR &&
qry)
{
qry->SetSQL("{:ret = call myFunction(&param1)}");

//Prepare the callable statement for execution
IGXCallableStmt *s = NULL;
hr = conn->PrepareCall(0, qry, NULL, NULL, &s);
if (hr == NOERROR &&
s)
{
// Set the in parameter values
IGXValList *params;
params = GXCreateValList();
params->SetValInt(":ret", 9999);
params->SetValInt("&param1", 20);

IGXResultSet *rs = NULL;

// Run the callable statement
hr = s->Execute(0, params, NULL, NULL, &rs);
if (hr == NOERROR &&
rs)
{
// Get the stored procedure's output value
IGXValList *paramsOut = NULL;
hr = s->GetParams(0, &paramsOut);
if (hr == NOERROR &&
paramsOut)
{


Related Topics
prepareCall( )PrepareCall( ) in the IDataConn Interface (deprecated)IGXDataConn interface

execute( )Execute( )

setParams( )SetParams( )

"Using Stored Procedures"


getResultSet( )


GetResultSet( )

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.


Example


//Run the callable statement
stmt.executeMultipleRS(0, inparms, null, null);

//Check if there is a result set
if (stmt.getMoreResults())
{
//Get the result set
IResultSet rsobj = stmt.getResultSet();
while (rsobj.fetchNext()) {
if (rsobj.getValueInt(1) == 100) {
System.out.println("Found record 100");
}
}
}
//Check if there is another result set
if (stmt.getMoreResults()) {
rsobj = stmt.getResultSet();
while (rsobj.fetchNext()) {
if (rsobj.getValueString(2) == 'George') {
System.out.println("Found record George");
}
}
}


hr = stmt->ExecuteMultipleRS(0, params, NULL, NULL);
DWORD moreResult = TRUE;
do {
hr = stmt->GetMoreResults(&moreResult);
if (moreResult == FALSE)
{
StreamResult("No more Results to process<BR>");
break;
}
else
{
IGXResultSet *pResultSet;
hr = stmt->GetResultSet(&pResultSet);
if (pResultSet)
{
DisplayResult(pResultSet);
pResultSet->Release();
}
}
} while(TRUE);


Related Topics
prepareCall( )PrepareCall( ) in the IDataConn Interface (deprecated)IGXDataConn interface

executeMultipleRS( )ExecuteMultipleRS( )

getMoreResults( )GetMoreResults( )

"Using Stored Procedures"


setParams( )


SetParams( )

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

execute( )Execute( )

getParams( )GetParams( )

"Using Stored Procedures"



ICallerContext 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.


Package

com.netscape.server


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:


// from within a servlet
com.netscape.server.IServerContext iplanetCtx;
ServletContext ctx = getServletContext();
iplanetCtx = (com.netscape.server.IServerContext) ctx;

com.netscape.server.ICallerContext callerCtx;
callerCtx = iplanetCtx.getCallerContext();

Identity id = callerCtx.getCallerIdentity();

if(id == null)
System.out.println("Servlet invoked by anonymous user");
else
System.out.println("Servlet invoked by user " + id.getName());


Example 2
The following sample code demonstrates the use of programmatic security from a servlet:


// from within a servlet
com.netscape.server.IServerContext iplanetCtx;
ServletContext ctx = getServletContext();
iplanetCtx = (com.netscape.server.IServerContxt) ctx;

com.netscape.server.ICallerContext callerCtx;
Identity managers = iplanetCtx.createIdentityByString("managers");

if(callerCtx.isCallerInRole(managers))
// caller is a member of the group managers
else
// caller is not a manager


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.



IGXColumn interface

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:

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


Methods


Table 3.13

Method

Description

getName( )GetName( )  

Returns the name of the column or alias.  

getNullsAllowed( )GetNullsAllowed( )  

Returns true if nullNULL values are allowed in the column.  

getPrecision( )GetPrecision( )  

Returns the precision, which is the maximum length or maximum number of digits, of the column.  

getScale( )GetScale( )  

Returns the scale, which is the number of digits to the right of the decimal point, of the column of type double.  

getSize( )GetSize( )  

Returns the maximum length, in number of bytes, allowed for a value in this column.  

getTable( )GetTable( )  

Returns the table object in which this column exists.  

getType( )GetType( )  

Returns the data type of the column.  


Example 1

The following example shows how to iterate through a table to get the names and types of the columns:


String htmlString;
IColumn col;
ITable tbl = conn.getTable("Products");

htmlString += "<h2>Products Table</h2>";
tbl.enumColumnReset();

while ((col = tbl.enumColumns()) != null) {
htmlString += "Column Name = ";
htmlString += col.getName();
htmlString += ", Column Type = ";
htmlString += col.getType();
htmlString += "<br>";
};
return result(htmlString)


HRESULT hr;
IGXDataConn *conn;
// Retrieve connection with CreateDataConn().
// Not shown here.

IGXTable *table = NULL;
hr = conn->GetTable("Products", &table);
if (hr == NOERROR &&
table)
{
// Stream back column information.
//
StreamResult("<h2>Products Table:</h2>");
hr = table->EnumColumnReset();
if (hr == NOERROR)
{
while (TRUE)
{
IGXColumn *column = NULL;
hr = table->EnumColumns(&column);
if (hr == NOERROR &&
column)
{
char buffer[256];
buffer[0] = '\0';

column->GetName(buffer, sizeof(buffer));
StreamResult("Column Name = ");
StreamResult(buffer);
StreamResult(", ");

DWORD type;
type = 0;
column->GetType(&type);
sprintf(buffer, "Column Type = %d", type);
StreamResult(buffer);
StreamResult("<br>");

column->Release();
}
else
{
// No more columns, exit loop.
break;
}
}
}
table->Release();
}


Example 2

The following example goes through all columns in a Products table and constructs an HTML string showing catalog information about each column:


ITable tbl = conn.getTable("Products");
htmlString += "<h2>Products Table:</h2>";

tbl.enumColumnReset();
IColumn col = tbl.enumColumns();
int loopcnt = 1;

while (col != null) {
htmlString += "Table Name = ";
htmlString += col.getTable().getName();
htmlString += "<br>";
htmlString += "Column Name=";
htmlString += col.getName();
htmlString += "<br>";
htmlString += ", Column Type=";
htmlString += col.getType();
htmlString += "<br>";
htmlString += "Nulls Allowed (T/F) = ";
htmlString += col.getNullsAllowed();
htmlString += "<br>";
htmlString += "Max Size = ";
htmlString += col.getSize();
htmlString += "<br>";
htmlString += "Precision = ";
htmlString += col.getPrecision();
htmlString += "<br>";

if (col.getType() == GX_DA_DATA_TYPES.GX_DA_TYPE_DOUBLE){
htmlString += "Scale = ";
htmlString += col.getScale();
htmlString += "<br>";
}
htmlString += "<br>";

col = tbl.enumColumns();
loopcnt++;
};
return result(htmlString + stdResFooter());
}
}


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


getName( )


GetName( )

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.


Tips

  • 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:


ITable tbl = conn.getTable("Products");
tbl.enumColumnReset();

htmlString += "<h2>Products Table:</h2>";
IColumn = tbl.enumColumns();
int loopcnt;
loopcnt = 1;

while (col != null) {
htmlString += "Column Name=";
htmlString += col.getName();
htmlString += "<br>";
col = tbl.enumColumns();
loopcnt++;
};
return result(htmlString + stdResFooter());
}
}


HRESULT hr;
IGXDataConn *conn;

// Retrieve connection with CreateDataConn().
// Not shown here.

IGXTable *table = NULL;
hr = conn->GetTable("Products", &table);
if (hr == NOERROR &&
table)
{
// Stream back column names.
//
StreamResult("<h2>Products Table:</h2>");
hr = table->EnumColumnReset();
if (hr == NOERROR)
{
while (TRUE)
{
IGXColumn *column = NULL;
hr = table->EnumColumns(&column);
if (hr == NOERROR &&
column)
{
char buffer[256];
buffer[0] = '\0';

column->GetName(buffer, sizeof(buffer));
StreamResult("Column Name = ");
StreamResult(buffer);
StreamResult(", ");

column->Release();
}
else
{
break;
}
}
}
}


Related Topics
"Getting Information About Columns or Fields"


getNullsAllowed( )


GetNullsAllowed( )

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:


ITable tbl = conn.getTable("Products");
tbl.enumColumnReset();

htmlString += "<h2>Products Table:</h2>";

IColumn col = tbl.enumColumns();
int loopcnt;
loopcnt = 1;

while (col != null) {
htmlString += "Column Name=";
htmlString += col.getName();
htmlString += "<br>";
htmlString += "Nulls Allowed (T/F) = ";
htmlString += col.getNullsAllowed();
htmlString += "<br>";
htmlString += "<br>";
col = tbl.enumColumns();
loopcnt++;
};
return result(htmlString + stdResFooter());
}
}


HRESULT hr;
IGXResultSet *resultset;

// Perform query here to retrieve resultset, not shown,
// with IGXDataConn::ExecuteQuery.

StreamResult("<h2>ResultSet column information:</h2>");
hr = resultset->EnumColumnReset();
if (hr == NOERROR)
{
while (TRUE)
{
IGXColumn *column = NULL;
hr = resultset->EnumColumns(&column);
if (hr == NOERROR &&
column)
{
char buffer[256];
buffer[0] = '\0';

column->GetName(buffer, sizeof(buffer));
StreamResult("Column Name = ");
StreamResult(buffer);
StreamResult(", ");

BOOL nullsAllowed;
nullsAllowed = FALSE;
column->GetNullsAllowed(&nullsAllowed);
sprintf(buffer, "Nulls Allowed = %s",(nullsAllowed
? "TRUE" : "FALSE"));
StreamResult(buffer);
StreamResult(", ");
}
else
{
// No more columns; exit loop.
break;
}
}
}


Related Topics
"Getting Information About Columns or Fields"


getPrecision( )


GetPrecision( )

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:


ITable tbl = conn.getTable("Products");
tbl.enumColumnReset();

htmlString += "<h2>Products Table:</h2>";

IColumn col = tbl.enumColumns();
int loopcnt;
loopcnt = 1;

while (col != null) {
htmlString += "Column Name=";
htmlString += col.getName();
htmlString += "<br>";
htmlString += "Precision = ";
htmlString += col.getPrecision();
htmlString += "<br>";
htmlString += "<br>";
col = tbl.enumColumns();
loopcnt++;
};
return result(htmlString + stdResFooter());
}
}


HRESULT hr;
IGXResultSet *resultset;

// Perform query here to retrieve resultset, not shown,
// with IGXDataConn::ExecuteQuery.

StreamResult("<h2>ResultSet column information:</h2>");
hr = resultset->EnumColumnReset();
if (hr == NOERROR)
{
while (TRUE)
{
IGXColumn *column = NULL;
hr = resultset->EnumColumns(&column);
if (hr == NOERROR &&
column)
{
char buffer[256];
buffer[0] = '\0';

column->GetName(buffer, sizeof(buffer));
StreamResult("Column Name = ");
StreamResult(buffer);
StreamResult(", ");

ULONG precision;
precision = 0;
column->GetPrecision(&precision);
sprintf(buffer, "Column precision = %d",precision);
StreamResult(buffer);
StreamResult("<br>");
}
else
{
// No more columns; exit loop.
break;
}
}
}


Related Topics
"Getting Information About Columns or Fields"


getScale( )


GetScale( )

Returns the scale, which is the number of digits to the right of the decimal point, of a column of type double.


Syntax
public int getScale()

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.


Rules

  • 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"


getSize( )


GetSize( )

Returns the maximum length, in number of bytes, allowed for a value in this column.


Syntax
public int getSize()

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.


Rules

  • 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:


ITable tbl = conn.getTable("Products");
tbl.enumColumnReset();

htmlString += "<h2>Products Table:</h2>";

IColumn col = tbl.enumColumns();
int loopcnt;
loopcnt = 1;

while (col != null) {
htmlString += "Column Name=";
htmlString += col.getName();
htmlString += "<br>";
htmlString += "Max Size = ";
htmlString += col.getSize();
htmlString += "<br>";
htmlString += "<br>";
col = tbl.enumColumns();
loopcnt++;
};
return result(htmlString + stdResFooter());
}
}


HRESULT hr;
IGXResultSet *resultset;

// Perform query here to retrieve resultset, not shown,
// with IGXDataConn::ExecuteQuery.

StreamResult("<h2>ResultSet column information:</h2>");
hr = resultset->EnumColumnReset();
if (hr == NOERROR)
{
while (TRUE)
{
IGXColumn *column = NULL;
hr = resultset->EnumColumns(&column);
if (hr == NOERROR &&
column)
{
char buffer[256];
buffer[0] = '\0';

column->GetName(buffer, sizeof(buffer));
StreamResult("Column Name = ");
StreamResult(buffer);
StreamResult(", ");

ULONG size;
size = 0;
column->GetSize(&size);
sprintf(buffer, "Max Size = %d", size);
StreamResult(buffer);
StreamResult(", ");
}
else
{
// No more columns; exit loop.
break;
}
}
}


Related Topics
"Getting Information About Columns or Fields"


getTable( )


GetTable( )

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.


Example


// Walk through all columns in Products table and construct
// an HTML string showing the table name for each column
ITable tbl = conn.getTable("Products");
tbl.enumColumnReset();
htmlString += "<h2>Products Table:</h2>";
IColumn col = tbl.enumColumns();
int loopcnt;
loopcnt = 1;
while (col != null) {
htmlString += "Table Name = ";
htmlString += col.getTable().getName();
htmlString += "<br>";
htmlString += "Column Name=";
htmlString += col.getName();
htmlString += "<br>";
htmlString += "<br>";
col = tbl.enumColumns();
loopcnt++;
};
return result(htmlString + stdResFooter());
}
}


// Walk through all columns in a resultset and stream
// back column information.

HRESULT hr;
IGXResultSet *resultset;

// Perform query here to retrieve resultset, not shown,
// with IGXDataConn::ExecuteQuery.

StreamResult("<h2>ResultSet column information:</h2>");
hr = resultset->EnumColumnReset();
if (hr == NOERROR)
{
while (TRUE)
{
IGXColumn *column = NULL;
hr = resultset->EnumColumns(&column);
if (hr == NOERROR &&
{
char buffer[256];
buffer[0] = '\0';

column->GetName(buffer, sizeof(buffer));
StreamResult("Column Name = ");
StreamResult(buffer);
StreamResult(", ");

// Get the table object in which this column exists
IGXTable *table;
table = NULL;
if (column->GetTable(&table) == NOERROR &&
table)
{
buffer[0] = '\0';
table->GetName(buffer, sizeof(buffer));
StreamResult("Column Table = ");
StreamResult(buffer);
StreamResult(", ");
table->Release();
}
// Process other column information


Related Topics
ITable Interface (deprecated)IGXTable interface

"Getting Information About Columns or Fields"


getType( )


GetType( )

Returns the data type of the column.


Syntax
public int getType()

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.


Usage





Variable

Description

GX_DA_TYPE_ERROR  

Error data type. See for more information.  

GX_DA_TYPE_BINARY  

All binary data types, including binary large objects (BLOBs).  

GX_DA_TYPE_DATETIME  

Timestamp (date and time) data type. See the GXDATETIME struct  

GX_DA_TYPE_DATE  

Date data type.  

GX_DA_TYPE_TIME  

Time data type.  

GX_DA_TYPE_DOUBLE  

Double and related data types, including real, float, and decimal data types.  

GX_DA_TYPE_LONG  

Long and related data types, including int.  

GX_DA_TYPE_STRING  

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.

GX_DA_TYPE_ERROR

GX_DA_TYPE_TIME

GX_DA_TYPE_BINARY

GX_DA_TYPE_DOUBLE

GX_DA_TYPE_DATETIME

GX_DA_TYPE_LONG

GX_DA_TYPE_DATE

GX_DA_TYPE_STRING

HRESULT, which is set to GXE_SUCCESS if the method succeeds.


Example


private static String getColumnString(IResultSet res, String colName) {

// Input parameter error checking
if((rs==null)||(rs.getRowNumber()==0)||(colName==null)) return null;

int colOrd=rs.getColumnOrdinal(colName);
IColumn col;

if((col=rs.getColumnByOrd(colOrd))==null) return null;
String valStr=null;

// Switch type
switch(col.getType()) {
case GX_DA_DATA_TYPES.GX_DA_TYPE_STRING:
valStr = rs.getValueString(colOrd);
break;
case GX_DA_DATA_TYPES.GX_DA_TYPE_LONG:
valStr=String.valueOf(rs.getValueInt(colOrd));
break;
case GX_DA_DATA_TYPES.GX_DA_TYPE_DATE:
case GX_DA_DATA_TYPES.GX_DA_TYPE_DATETIME:
case GX_DA_DATA_TYPES.GX_DA_TYPE_TIME:
valStr = rs.getValueDateString(colOrd);
break;
case GX_DA_DATA_TYPES.GX_DA_TYPE_DOUBLE:
valStr = String.valueOf(rs.getValueDouble(colOrd));
break;
default: // Unknown type, so error out
// Fall thru to the return. Note that valStr is null;
};
return valStr;


Related Topics
"Getting Information About Columns or Fields"



IContext Interface

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.


Package

com.kivasoft


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;

kivaContext = this.context;


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;

// legal cast within iAS

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:

HttpServletRequest req;

HttpServletRequest2 req2;

req2 = (HttpServletRequest2) req; // legal cast within iPlanet Application Server

AppLogic al = req2.getAppLogic();

com.kivasoft.IContext kivaContext;

kivaContext = al.context;


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.



IGXDataConn interface

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:.

IDataConn conn;

if((conn = createDataConn(0, GX_DA_DAD_DRIVERS.GX_DA_DRIVER_ODBC, "CATALOG", "CATALOG", "steve", "pass7878")) == null)

. . .


Package Include File

com.kivasoft gxidata.h


Methods


Table 3.15

Method

Description

closeConn( )CloseConn( )  

Explicitly closes a database connection.  

createTrigger( )CreateTrigger( )  

Creates a new trigger object in the specified table.

 

disableTrigger( )DisableTrigger( )  

Disables a trigger associated with a specified table. This feature is supported by Oracle databases only.  

dropTrigger( )DropTrigger( )  

Removes a trigger from a specified table.

 

enableTrigger( )EnableTrigger( )  

Enables a trigger for a specified table. This feature is supported by Oracle databases only.  

executeQuery( )ExecuteQuery( )  

Executes a flat query on the data connection.  

getConnInfo( )GetConnInfo( )  

Returns database and user information about the current database connection.  

getConnProps( )GetConnProps( )  

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.  

getTable( )GetTable( )  

Returns the table definition object for the specified table.  

getTables( )GetTables( )  

Returns an IValListIGXValList of database tables or views that are available to the specified user.  

prepareCall( )PrepareCall( )  

Creates an ICallableStmtIGXCallableStmt object that contains a call to a stored procedure.  

prepareQuery( )PrepareQuery( )  

Prepares a flat query object for subsequent execution.  

setConnProps( )SetConnProps( )  

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

IGXSequence interface

"Running Hierarchical Queries"

"Inserting Records in a Database," "Updating Records in a Database," and "Deleting Records From a Database"


closeConn( )


CloseConn( )

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.


Rules

  • 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.


Example


IDataConn conn;
if((conn = createDataConn(0, GX_DA_DAD_DRIVERS.GX_DA_DRIVER_ODBC, "CATALOG", "CATALOG", "steve", "pass7878")) == null)
{
// Cannot connect - return error message
result("Failed to connect to Catalog db");
return null;
};
// Connected - return the data connection object
// used for subsequent operations on the database
return conn;
};
. . . perform database operations . . .
// Explicitly close the connection
int closeResult;
closeResult=conn.closeConn(0);


Related Topics
createDataConn( )CreateDataConn( ) in the AppLogic class (deprecated)GXAppLogic class

"About Database Connections"


createTrigger( )


CreateTrigger( )

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:

"AFTER INSERT, UPDATE"

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.


Tips

  • 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.


Example


IDataConn conn;
conn = createDataConn(0, GX_DA_DAD_DRIVERS.GX_DA_DRIVER_ODBC,
"personnelDB", "personnelDB", "sandra", "pass7878");
conn.createTrigger("employees", "ProcessNew",
"FOR EACH ROW WHEN(title='Director')",
"AFTER INSERT", "[SQL instruction here]";
conn.enableTrigger("employees", "ProcessNew");


IGXDataConn *conn = NULL;
HRESULT hr;

hr = CreateDataConn(0, GX_DA_DRIVER_ODBC, conn_params, NULL, &conn);
if (hr == NOERROR &&
conn)
{
hr = conn->CreateTrigger("employees", "ProcessNew",
"FOR EACH ROW WHEN(title='Director')",
"AFTER INSERT",
"[SQL instruction here]");
if (hr == NOERROR)
{
conn->EnableTrigger("employees", "ProcessNew");
}
conn->Release();
}


Related Topics
disableTrigger( )DisableTrigger( )

dropTrigger( )DropTrigger( )

enableTrigger( )EnableTrigger( )


disableTrigger( )


DisableTrigger( )

Disables a trigger associated with a specified table. This feature is supported by Oracle databases only.


Syntax
public int disableTrigger(
   String pTable,
   String pName);

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

dropTrigger( )DropTrigger( )

enableTrigger( )EnableTrigger( )


dropTrigger( )


DropTrigger( )

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


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.


Example
CloseConn( )


Related Topics
createTrigger( )CreateTrigger( ); disableTrigger( )DisableTrigger( )

dropTrigger( )DropTrigger( )


executeQuery( )


ExecuteQuery( )

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.


Rules


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.


Example 1


// Create the flat query object
IQuery qry=createQuery();

// Set up the query
qry.setTables("CTLcust");
qry.setFields("CustomerID, Customer");
qry.setWhere("Customer"+"="+String.valueOf(custId));

// Execute the query
IResultSet rs=conn.executeQuery(0, qry, null, null);
// Check for a non empty result
if((rs!=null)&&(rs.getRowNumber()>0))
   return result("Sorry, this user ("+
   firstName+" "+lastName+") already exists");
// Otherwise, process the result set


Example 2


// Set up result set buffering for query
IValList props;
props = GX.CreateValList();
// Turn on result set buffering
props.setValString("RS_BUFFERING", "TRUE");
// Specify the maximum number of rows to buffer
props.setValInt("RS_MAX_ROWS", 50);
IQuery qry = createQuery();
. . . define query properties . . .
// Attempt to execute query with result set buffering
IResultSet rs = conn.executeQuery(0, qry, null, props);


// Create a vallist for loadQuery() parameters
IGXValList *pList=GXCreateValList();

if(pList) {
GXSetValListString(pList, "ssn", pSsn);

// Load the query from the query file
IGXQuery *pQuery=NULL;
if(((hr=LoadQuery(SelCustAccts.gxq", "SelCustAccts", 0, pList,
   &pQuery))==GXE_SUCCESS)&&pQuery) {

// Execute the query
IGXResultSet *pRset=NULL;
if(((hr=pConn->ExecuteQuery(0, pQuery, NULL, NULL,
          &pRset))==GXE_SUCCESS)&&pRset) {

// Process the result set


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

"About Database Connections"


getConnInfo( )


GetConnInfo( )

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.


getConnProps( )


GetConnProps( )

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:


Table 3.16

Key

Value

"cache_free_entries"  

An integer indicating the number of slots set for free connections.  

"cache_alloc_size"  

An integer indicating the initial number of slots in the connection cache.  

"conn_db_vendor"  

A string that identifies the database vendor, for example, "Oracle" or "Sybase."  

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


getDriver( )


GetDriver( )

Returns the identifier of the data source driver that the current database connection is using.


Syntax
public int getDriver()

HRESULT GetDriver(
DWORD *pdwDriver);

pdwDriver. Pointer to the variable that contains the returned driver information, which can be one of the following:

GX_DA_DRIVER_ODBC

GX_DA_DRIVER_SYBASE_CTLIB

GX_DA_DRIVER_MICROSOFT_JET

GX_DA_DRIVER_MICROSOFT_SQL

GX_DA_DRIVER_INFORMIX_SQLNET

GX_DA_DRIVER_INFORMIX_CLI

GX_DA_DRIVER_INFORMIX_CORBA

GX_DA_DRIVER_DB2_CLI

GX_DA_DRIVER_ORACLE_OCI

GX_DA_DRIVER_DEFAULT


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.

GX_DA_DRIVER_ODBC

GX_DA_DRIVER_SYBASE_CTLIB

GX_DA_DRIVER_MICROSOFT_JET

GX_DA_DRIVER_MICROSOFT_SQL

GX_DA_DRIVER_INFORMIX_SQLNET

GX_DA_DRIVER_INFORMIX_CLI

GX_DA_DRIVER_INFORMIX_CORBA

GX_DA_DRIVER_DB2_CLI

GX_DA_DRIVER_ORACLE_OCI

GX_DA_DRIVER_DEFAULT

HRESULT, which is set to GXE_SUCCESS if the method succeeds.


getTable( )


GetTable( )

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.


Tips


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.


Example


ITable table = dbConn.getTable("CTLcust");
if(table==null) return result("Can't find the table: "+"CTLcust");
// Otherwise, process the table columns
int cCustId = table.getColumnOrdinal("CustomerID");
int cFirst = table.getColumnOrdinal("FirstName");
. . .


// Create the data connection
IGXDataConn *pConn=NULL;

if(((hr=GetOBDataConn(&pConn))==GXE_SUCCESS)&&pConn) {
IGXTable *pTable=NULL;

// Get the table
if(((hr=pConn->GetTable("OBTransaction",
   &pTable))==GXE_SUCCESS)&&pTable) {

// Look up the column ordinals for the table
ULONG transTypeCol=0;
pTable->GetColumnOrdinal("transType", &transTypeCol);
ULONG postDateCol=0;
pTable->GetColumnOrdinal("postDate", &postDateCol);
ULONG acctNumCol=0;
pTable->GetColumnOrdinal("acctNum", &acctNumCol);
ULONG amountCol=0;
pTable->GetColumnOrdinal("amount", &amountCol);


Related Topics
ITable Interface (deprecated)IGXTable interface

createDataConn( )CreateDataConn( ) in the AppLogic class (deprecated)GXAppLogic class

Val classGXVAL struct

IValList interfaceIGXValList interface

"About Database Connections"


getTables( )


GetTables( )

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:

  • underscore (_) for single characters

  • percent sign (%) for any sequence of zero or more 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.


Rules

  • 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

"About Database Connections"


prepareCall( )


PrepareCall( )

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

dwFlags. Specify 0.

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.

pProps. Specify nullNULL.

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.


Rules

  • 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, &param1. 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


// Create the database connection.
IDataConn conn_rtest = createDataConn(0, GX_DA_DAD_DRIVERS.GX_DA_DRIVER_DEFAULT,
/* Datasource name */ "ksample",
/* Database name */ "",
/* userName */ "kdemo",
/* password */ "kdemo");

//Write command to call stored procedure
String theProc = "{call myProc1(&p1, :p2)}";
IQuery myquery;
myquery = createQuery();
myquery.setSQL(theProc);

//Prepare the callable statement for execution
ICallableStmt myStmt;
myStmt = conn_rtest.prepareCall(0, myquery, null, null);

// Set parameters and run the callable statement


IGXValList *conn_params;

// Set connection parameters
conn_params = GXCreateValList();
conn_params->SetValString("DSN", "salesDB");
conn_params->SetValString("DB", "salesDB");
conn_params->SetValString("USER", "steve");
conn_params->SetValString("PSWD", "pass7878");

IGXDataConn *conn = NULL;
HRESULT hr;

// Create the data connection
hr = CreateDataConn(0, GX_DA_DRIVER_ODBC, conn_params, NULL, &conn);
if (hr == NOERROR &&
conn)
{
// Create query that contains the call to the
// stored procedure
IGXQuery *qry = NULL;

hr = CreateQuery(&qry);
if (hr == NOERROR &&
qry)
{
qry->SetSQL("{:ret = call myFunction(:param1)}");
IGXCallableStmt *s = NULL;

// Prepare the callable statement for execution
hr = conn->PrepareCall(0, qry, NULL, NULL, &s);
if (hr == NOERROR &&
s)

// Set parameters and run callable statement


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


prepareQuery( )


PrepareQuery( )

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

dwFlags. Specify 0.

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.

pProps. Specify nullNULL.

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.


Example


// Create the data connection
IDataConn conn;
conn = createDataConn(0, GX_DA_DAD_DRIVERS.GX_DA_DRIVER_DEFAULT, "Orders", "Orders", "user", "password");

// Create the flat query and prepared query objects
IQuery qry = createQuery();
IPreparedQuery pqry;
IValList params;
params = GX.CreateValList();

// Set up the INSERT statement
qry.setSQL("INSERT INTO TABLE Products (ProductName, QuantityPerUnit) VALUES (:name, :quant)");

// Prepare the flat query
pqry = conn.prepareQuery(0, qry, null, null);

// Specify a set of query parameters, then execute
params.setValString(":name","Chicken Dumplings");
params.setValString(":quant", "48 packages");
IResultSet rs1 = pqry.execute(0, params, null, null);
. . . process rs1. . .

// Specify different set of query parameters, then execute
params.setValString(":name", "Rice Noodles");
params.setValString(":quant", "96 packages");
IResultSet rs2 = pqry.execute(0, params, null, null);
. . . process rs2. . .


// Create an Insert query
IGXQuery *pUserQuery=NULL;
if(((hr=CreateQuery(&pUserQuery))==GXE_SUCCESS)&&pUserQuery) {
pUserQuery->SetSQL("INSERT INTO OBUser(userName, password, userType,
   eMail) VALUES (:userName, :password, :userType, :eMail)");

// Create another Insert query
IGXQuery *pAcctQuery=NULL;
if(((hr=CreateQuery(&pAcctQuery))==GXE_SUCCESS)&&pAcctQuery) {
pAcctQuery->SetSQL("INSERT INTO OBAccount VALUES (:acctNum, :ssn,
   :acctType, :balance)");

// Create the data connection and prepared query objects
IGXDataConn *pConn=NULL;

if(((hr=GetOBDataConn(&pConn))==GXE_SUCCESS)&&pConn) {
IGXPreparedQuery *pUserPQuery=NULL;
IGXPreparedQuery *pAcctPQuery=NULL;

// Create prepared queries
pConn->PrepareQuery(0, pUserQuery, NULL, NULL, &pUserPQuery);
pConn->PrepareQuery(0, pAcctQuery, NULL, NULL, &pAcctPQuery);


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

"About Database Connections"


setConnProps( )


SetConnProps( )

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:


Table 3.17

Key

Value

"cache_free_entries"  

An integer indicating the number of slots set for free connections.  

"cache_alloc_size"  

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.



IGXDataConnSet interface

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:.

IDataConnSet connSet;

connSet = createDataConnSet();


Package Include File

com.kivasoftgxidata.h


Methods


Table 3.18

addConn( )AddConn( )  

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

"About Database Connections"


addConn( )


AddConn( )

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.


Rules


Return Value
GXE.SUCCESS if the method succeeds.

HRESULT, which is set to GXE_SUCCESS if the method succeeds.


Example


IDataConnSet connSet;
connSet = createDataConnSet();
// Specify query / db connection pairs
connSet.addconn("employee", conn_empDB);
connSet.addconn("sales", conn_salesDB);
IHierQuery hqry;
// Load the GXQ file with the db connection set
hqry = loadHierQuery("employeeReport.gxq",connSet, 0, null);
// Run the report
evalTemplate("employeeReport.html", hqry);


Related Topics
createDataConnSet( )CreateDataConnSet( ) in the AppLogic class (deprecated)GXAppLogic class

"About Database Connections"



IEnumObject Interface



IGXEnumObject interface

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


Methods


Table 3.19

Method

Description

enumCount( )EnumCount( )  

Returns the number of IObjectIGXObject instances in an IEnumObjectIGXEnumObject.  

enumNext( )EnumNext( )  

Returns the next IObjectIGXObject instance in an IEnumObjectIGXEnumObject.  

enumReset( )EnumReset( )  

Resets to the first IObjectIGXObject instance in an IEnumObjectIGXEnumObject.  


Related Topics

enumEvents( )EnumEvents( ) in the IAppEventMgr InterfaceIGXAppEventMgr interface


enumCount( )


EnumCount( )

Returns the number of IObjectIGXObject instances in an IEnumObjectIGXEnumObject.


Syntax
public int enumCount()

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.


// suppose appEventMgr holds a valid reference to
// an IAppEventMgr instance

// Get the Enumeration object for all registered appevents
IEnumObject enumObj = appEventMgr.enumEvents();

// Retrieve the count of registered appevents
int count = enumObj.enumCount();
try {
p.writeObject("Number of Registered Events: ");
p.writeInt(count);
} catch (IOException e) {
return streamResult("Failed to write to report file<br>");
}

// Reset to the first object in the enumeration object
enumObj.enumReset(0);

// Iterate through all the enumeration instances
while (count > 0) {

// Process the objects.
}


IGXEnumObject *pEObjs = NULL;
ULONG ulCount = 0;

// suppose pAppEventMgr has a valid reference to IGXAppEventMgr object

// Get the Enumeration object for all registered appevents
hr = pAppEventMgr->EnumEvents(&pEObjs);

// Retrieve the count of registered appevents
hr = pEObjs->EnumCount(&ulCount);

fprintf(fp, "Number of Registered Events: %d\n", ulCount);

// Reset the next enumeration object to be the first instance
hr = pEObjs->EnumReset(0);

// Iterate through all the enumeration instances
while (ulCount--) {
// Process the objects
}


Related Topics
enumEvents( )EnumEvents( ) in the IAppEventMgr InterfaceIGXAppEventMgr interface

enumNext( )EnumNext( )

enumReset( )EnumReset( )


enumNext( )


EnumNext( )

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.



// Suppose appEventMgr holds a valid reference to AppEvent Manager

// Get the Enumeration object for all registered appevents
IEnumObject enumObj = appEventMgr.enumEvents();

// Retrieve the count of registered appevents
int count = enumObj.enumCount();
try {
p.writeObject("Number of Registered Events: ");
p.writeInt(count);
} catch (IOException e) {
return streamResult("Failed to write to report file<br>");
}

// Reset to the first object in the enumeration object
enumObj.enumReset(0);

// Iterate through all the enumeration instances
while (count > 0) {
IObject vListObj = enumObj.enumNext();
if (vListObj instanceof IAppEventObj) {
IAppEventObj vAppEventObj = (IAppEventObj)vListObj;

// process the appevent
}
}


// Retrieve the count of registered appevents
hr = pEObjs->EnumCount(&ulCount);

// Reset to the first object
hr = pEObjs->EnumReset(0);

// Iterate through all the enumeration instances
while (ulCount--) {
IGXObject *pObj = NULL;

// Get the next instance
hr = pEObjs->EnumNext(&pObj);
if ((hr != NOERROR) || (pObj == NULL)) {
pEObjs->Release();
return StreamResult("EnumNext failed!<br>");
}

// Make sure the object supports the IGXAppEventObj
// interface (it should)
IGXAppEventObj* pAEObj = NULL;
hr = pObj->QueryInterface(IID_IGXAppEventObj, (LPVOID *)&pAEObj);
pObj->Release();
if ((hr != NOERROR) || (pAEObj == NULL)) {
pAEObj->Release();
return StreamResult("QueryInterface on EnumNext Obj failed!<br>");
}

// Process the objects

// Release when done.
pAEObj->Release();
}


Related Topics
enumEvents( )EnumEvents( ) in the IAppEventMgr InterfaceIGXAppEventMgr interface

enumCount( )EnumCount( )

enumReset( )EnumReset( )


enumReset( )


EnumReset( )

Resets to the first IObjectIGXObject instance in an IEnumObjectIGXEnumObject.


Syntax
public int enumReset(
   int dwFlags)

HRESULT EnumReset(
   DWORD dwFlags);

dwFlags. Specify 0.


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.


Example


// Retrieve the count of objects in the IEnumObject
int count = enumObj.enumCount();

// Reset to the first object in the enumeration object
enumObj.enumReset(0);

// Iterate through all the enumeration instances
while (count > 0) {
IObject vListObj = enumObj.enumNext();
// Process the objects


// Retrieve the count of objects in the IGXEnumObject
hr = pEObjs->EnumCount(&ulCount);

// Reset the next enumeration object to be the first instance
hr = pEObjs->EnumReset(0);

// Iterate through all the enumeration instances
while (ulCount--) {
// Process the objects
}


Related Topics
enumEvents( )EnumEvents( ) in the IAppEventMgr InterfaceIGXAppEventMgr interface

enumCount( )EnumCount( )

enumNext( )EnumNext( )



IError Interface (deprecated)

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.



IGXError interface

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:

IDataConn conn;

conn = createDataConn(...);

IError error;

error = (IError) conn;

IGXDataConn *conn;

IGXError *error;

conn->QueryInterface(IID_IGXError, (LPVOID *) &error);


Package Include File

com.kivasoft gxierror.h


Methods


Table 3.20

Method

Description

getErrorCode( )GetErrorCode( )  

Returns the current error code as a string.  

getErrorCodeNum( )GetErrorCodeNum( )  

Returns the current error code as a number.  

getErrorMessage( )GetErrorMessage( )  

Returns the message associated with the current error code.  

getErrorFacility( )GetErrorFacility( )  

Returns a description of the facility that generated an error code.  


getErrorCode( )


GetErrorCode( )

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


getErrorCodeNum( )


GetErrorCodeNum( )

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


getErrorMessage( )


GetErrorMessage( )

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


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.



IGXHierQuery interface

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:

Asia 170

China 110

Japan 60

Europe 80

France 70

Portugal 10

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:

IHierQuery hqry;

hqry = createHierQuery();


Package Include File

com.kivasoft gxidatap.h


Methods


Table 3.21

Method

Description

addQuery( )AddQuery( )  

Adds a child query to a parent query, defining an additional level of detail in the hierarchical query.  

delQuery( )DelQuery( )  

Removes a child query from its parent query.  

execute( )Execute( )  

Executes a hierarchical query and returns a hierarchical result set.  


Example 1


// Create the flat query
IQuery qry = createQuery();
qry.setTables("CTLusers");
qry.setFields("loginName, Password, AccessLevel")
qry.setOrderBy("LoginName);

// Create the hierarchical query used for template processing
IHierQuery hqry = createHierQuery();

// Add the flat query object and data connection to hqry
hqry.addQuery(qry, conn, "USERS", "", "");

// Pass hierarchical query to evalTemplate() for reporting
if(evalTemplate("apps/template/userinfo.html", hqry)==0)
return result("");
else
return result("Failed to Generate HTML");
}



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

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




Related Topics

createHierQuery( )createHierQuery( ) in the AppLogic class (deprecated)GXAppLogic class

"Writing Hierarchical Queries"


addQuery( )


AddQuery( )

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.


Rules


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
IQuery qry = createQuery();
qry.setTables("CTLusers");
qry.setFields("loginName, Password, AccessLevel")
qry.setOrderBy("LoginName);

// Create the hierarchical query used for template processing
IHierQuery hqry = createHierQuery();

// Add the flat query object and data connection to hqry
hqry.addQuery(qry, conn, "USERS", "", "");

// Pass hierarchical query to evalTemplate() for reporting
if(evalTemplate("apps/template/userinfo.html", hqry)==0)
return result("");
else
return result("Failed to Generate HTML");
}


Example 2


// Create the City flat query
IQuery qryCTY;
qryCTY = createQuery();
qryCTY.setTables("emp");
qryCTY.setFields("city, Sum(salary) as sumsalary");
qryCTY.setGroupBy("city");

// Create the Employee flat query
IQuery qryEMP;
qryEMP = createQuery();
qryEMP.setTables("emp");
qryEMP.setFields("name, salary, city");

IHierQuery hqry;
hqry = createHierQuery();
// Add both queries to the hierarchical query object
hqry.addQuery(qryCTY, conn, "CTY", "", "");
hqry.addQuery(qryEMP, conn, "EMP", "CTY", "EMP.emp.city = 'CTY.city'");
// Run the report
evalTemplate("GXApp/EmpTrack/Templates/report.html", hqry);
return result(null);


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


delQuery( )


DelQuery( )

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.


Example


// Create the City flat query
IQuery qryCTY;
qryCTY = createQuery();
qryCTY.setTables("emp");
qryCTY.setFields("city, Sum(salary) as sumsalary");
qryCTY.setGroupBy("city");

// Create the Employee flat query
IQuery qryEMP;
qryEMP = createQuery();
qryEMP.setTables("emp");
qryEMP.setFields("name, salary, city");

IHierQuery hqry;
hqry = createHierQuery();
// Add both queries to the hierarchical query object
hqry.addQuery(qryCTY, conn, "CTY", "", "");
hqry.addQuery(qryEMP, conn, "EMP", "CTY", "EMP.emp.city = 'CTY.city'");

// Execute the hierarchical query
IHierResultSet hrs = hqry.execute(0, 0, null);
if(hrs.getRowNumber("USERS")!=0)
// Process rows in result set . . .

// Remove child query from hierarchical query
hqry.delQuery("qryEMP");

// Pass parent query to evalTemplate() for reporting
if(evalTemplate("apps/template/ctySumm.html", hqry)==0)
return result("");
else
return result("Failed to Generate HTML");
}


Related Topics
createHierQuery( )createHierQuery( ) in the AppLogic class (deprecated)AppLogic class (deprecated)

loadHierQuery( ) in the AppLogic class (deprecated)

"Writing Hierarchical Queries"


execute( )


Execute( )

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

dwTimeout. Specify 0 (zero).

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.


Example


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


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.



IGXHierResultSet interface

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:

IHierResultSet hrs

hrs = hqry.execute(0, 0, null);

IGXHierResultSet *hrs = NULL;

HRESULT hr;

hr = hqry->Execute(0, 0, NULL, &hrs);


Package Include File

com.kivasoft gxidatap.h


Methods


Table 3.22

Method

Description

count( )Count( )  

Returns the total number of rows retrieved so far from the data source for the specified child query.  

getColumn( )GetColumn( )  

Returns the column definition for the column with the specified name in the specified child query.  

getColumnByOrd( )GetColumnByOrd( )  

Returns the column definition for the column in the specified ordinal position for the specified child query.  

getResultSet( )GetResultSet( )  

Returns the result set for a specified child query.  

getRowNumber( )GetRowNumber( )  

Returns the number of the current row for the specified child query in the hierarchical result set.  

getValueDateString( )GetValueDateString( )  

Returns the value of a Date type column, as a string, from the specified child query in the result set.  

getValueDouble( )GetValueDouble( )  

Returns the value of a double type column from the specified child query in the result set.  

getValueInt( )GetValueInt( )  

Returns the value of an int type column from the specified child query in the result set.  

getValueString( )GetValueString( )  

Returns the value of a string type column from the specified child query in the result set.  

moveNext( )MoveNext( )  

Moves to the next row for the specified child query in the result set.  

moveTo( )MoveTo( )  

Moves to the specified row for the specified child query in the result set.  


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:


// Create the hierarchical query
IHierQuery hqry = createHierQuery();
hqry.addQuery(qry, conn, "USERS", "", "");

// Execute the query
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=hrs.getValueString("USERS", "AccessLevel");
String selAdmin, selNormal;
if(access.compareTo("AccessAdmin")==0)
{
selAdmin="<option selected>"+"AccessAdmin"+"</option>\n";
selNormal="<option>Normal</option>\n";
}
else
{
selAdmin="<option>"+"AccessAdmin"+"</option>\n";
selNormal="<option selected>Normal</option>\n";
}
String select="<select name=accessControlLevel>\n"+selNormal+selAdmin+"</select>";

TemplateMapBasic tMap=new TemplateMapBasic();
tMap.put("ACCESS", select);

int ers = evalTemplate(template, (ITemplateData) hrs, tMap);
if (ers==0)
return result("");
else
return result("Failed to Generate HTML");
}


LPSTR templateName;
IGXDataConn *conn;
IGXQuery *qry;
LPSTR wantedUser;

// Not shown here, creation of data connection and creation
// of query of users.

IGXHierQuery *hqry = NULL;
CreateHierQuery(&hqry);
hqry->AddQuery(qry, conn, "USERS", "", "");

// Execute the hierarchical query.
IGXHierResultSet *hrs = NULL;
HRESULT hr;
hr = hqry->Execute(0, 0, NULL, &hrs);
if (hr == NOERROR && hrs)
{
ULONG i;
if (hrs->GetRowNumber("USERS", &i) == NOERROR &&
i > 0)
{
// The current row is row 1, so there is at least
// one user returned in the USERS sub-query.
//
// The business logic here is to check the user's
// access level, and show different listbox options
// depending on the level.
//
LPSTR selAdmin;
LPSTR selNormal;
char access[64];
access[0] = '\0';
char buffer[1024];
buffer[0] = '\0';

hr = hrs->GetValueString("USERS", "AccessLevel", access,
         sizeof(access));
if (hr == NOERROR &&
strcmp(access, "AccessAdmin") == 0)
{
selAdmin = "<option selected>AccessAdmin</option>";
selNormal = "<option>Normal</option>";
}
else
{
selAdmin = "<option>AccessAdmin</option>";
selNormal = "<option selected>Normal</option>";
}
sprintf(buffer,
"<select name=accessControlLevel>\n%s%s</select>",
selAdmin,
selNormal);

// We have a template map which we fill
// with dynamic values. The template should
// refer to these values in gx cell
// placeholders.
//
GXTemplateMapBasic *map = new GXTemplateMapBasic();
IGXBuffer *b;
b = GXCreateBufferFromString(buffer);
map->Put("ACCESS", b);
b->Release();
b = GXCreateBufferFromString(access);
map->Put("ACCESS_LEVEL", b);
b->Release();
hr = EvalOutput(templateName,
(IGXTemplateData *) hrs,
(IGXTemplateMap *) map,
NULL, NULL);
map->Release();
}
else
{
// No users returned in the USERS sub-query.
//
StreamResult("No user matches the login name: ");
StreamResult(wantedUser);
}
hrs->Release();
}


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"


count( )


Count( )

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.


Example


// Create the hierarchical query
IHierQuery hqry = createHierQuery();
hqry.addQuery(qry, conn, "USERS", "", "");
// Execute the query
IHierResultSet hrs = hqry.execute(0, 0, null);
// Determine whether result returned match
if(hrs.count("USERS")==0)
   return result("No user matches loginname: "+wantedUser);
String access=hrs.getValueString("USERS", "AccessLevel");


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"


getColumn( )


GetColumn( )

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.


Rules

  • The specified child query must exist in the result set.

  • The specified column name must exist in the result set.

Tips

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 col;
col = hrs.getColumn("USERS", "UserID")
. . . process column info using IColumn methods . . .


IGXHierResultSet *hrs = NULL;

// Not shown here, execution of hierarchical query
// that retrieves the hierarchical resultset.

IGXColumn *col = NULL;
HRESULT hr;
hr = hrs->GetColumn("INVOICES", "Date", &col);
if (hr == NOERROR &&col)
{
// Call column methods, such as IGXColumn::GetName() here.

col->Release();
}


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"


getColumnByOrd( )


GetColumnByOrd( )

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.


Rules

  • 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 . . .

IGXHierResultSet *hrs = NULL;

// Not shown here, execution of hierarchical query

// that retrieves the hierarchical resultset.

IGXColumn *col = NULL;

HRESULT hr;

hr = hrs->GetColumnByOrd("INVOICES", 1, &col);

if (hr == NOERROR && col)

{

// Call column methods, such as IGXColumn::GetName() here.

col->Release();

}


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"


getResultSet( )


GetResultSet( )

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

if (hrs == null)

{

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

IGXResultSet *pRset=NULL;

if(((hr=pHRset->GetResultSet("SelCusts",

   &pRset))==GXE_SUCCESS)&&pRset) {


Related Topics
"Getting Data From a Flat Query's Result Set"


getRowNumber( )


GetRowNumber( )

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", "", "");

// Execute the query

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");

String selAdmin, selNormal;

if(access.compareTo("AccessAdmin")==0)

{

selAdmin="<option selected>"+"AccessAdmin"+"</option>\n";

selNormal="<option>Normal</option>\n";

}

else

{

selAdmin="<option>"+"AccessAdmin"+"</option>\n";

selNormal="<option selected>Normal</option>\n";

}

String select="<select name=accessControlLevel>\n"+selNormal+selAdmin+"</select>";

TemplateMapBasic tMap=new TemplateMapBasic();

tMap.put("ACCESS", select);

int ers = evalTemplate(template, (ITemplateData) rs, tMap);

if (ers==0)

return result("");

else

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"


getValueDateString( )


GetValueDateString( )

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.

nVal. Length of the variable.


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:

Jan 26 1998 12:35:00


Rule
The specified column must be a Date, Date Time, or Time data type.


Return Value
The date value as a string, or null for failure (such as an invalid column number or data type mismatch).

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.

char buffer[256];

buffer[0] = '\0';

HRESULT hr;

hr = hrs->GetValueDateString("INVOICES", "ShipDate", buffer, sizeof(buffer));


Related Topics
getValueDouble( )GetValueDouble( )

getValueInt( )GetValueInt( )

getValueString( )GetValueString( )


getValueDouble( )


GetValueDouble( )

Returns the value of a double type column from the specified child query in the result set.


Syntax
public double getValueDouble(
   String qryName,
   String colName)

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

getValueInt( )GetValueInt( )

getValueString( )GetValueString( )


getValueInt( )


GetValueInt( )

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


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.

nVal. Length of the variable.


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.

char buffer[256];

buffer[0] = '\0';

HRESULT hr;

hr = hrs->GetValueString("CUSTOMERS", "Country", buffer, sizeof(buffer));

if (hr == NOERROR)

{

StreamResult("The customer lives in the country of ");

StreamResult(buffer);

StreamResult(".<br>");

}


Related Topics
getValueDateString( )GetValueDateString( )

getValueDouble( )GetValueDouble( )

getValueInt( )GetValueInt( )


moveNext( )


MoveNext( )

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"


moveTo( )


MoveTo( )

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.


Rules

  • 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 Interface

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


Methods


Table 3.23

Method

Description

addListItem( )  

Adds an item to a list.  

setListSelection( )  

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


addListItem( )

Adds an item to a list.


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:

<SELECT NAME="TVShow">

%gx type=tile id=myList%

<OPTION VALUE="%gx type=cell id=myList.value% %/gx%"

%gx

type=cell

id=myList.isEqualToExpression(

   myList.value=myList.ListSelection)%SELECTED

%/gx%

>

%gx type=cell id=myList.label%%/gx%

%/gx%

</SELECT>


setListSelection( )

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.



ILock Interface



IGXLock interface

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


Methods


Table 3.24

Method

Description

changeMode( )ChangeMode( )  

Changes the lock mode of a currently locked object. This method is not available for the lock interface implemented by state and session objects.  

lock( )Lock( )  

Locks an object.  

unlock( )Unlock( )  

Unlocks a previously locked object.  


changeMode( )


ChangeMode( )

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.


lock( )


Lock( )

Locks an object.


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

"Starting a Session"


unlock( )


Unlock( )

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