|
C++ Helper Functions
This appendix contains information about C++ helper functions.
The following helper functions are described in this appendix:
GXContextCreateDataConn( )
Creates a new data connection object and opens a connection to a database or data source.
Syntax
HRESULT GXContextCreateDataConn(
IGXContext *pContext,
DWORD flags,
DWORD driver,
IGXValList *props,
IGXDataConn **ppConn);
pContext.
A pointer to an IGXContext object, which provides access to Netscape Application Server services. Specify m_pContext if accessing this helper function from a manager class; otherwise, use m_pModule->m_pContext.
flags.
One or more optional flags used for connecting to the specified data source.
The caller can pass one parameter from both mutually exclusive pairs, as shown in the following example:
(GX_DA_CACHED | GX_DA_CONN_BLOCK)
Specify 0 (zero) to use the system's default settings: GX_DA_CACHED and GX_DA_CONN_BLOCK
driver.
Specify one of the following:
If GX_DA_DRIVER_DEFAULT is specified, the Netscape Application Server evaluates the drivers and their associated priorities set in the registry to determine the driver to use. Specify GX_DA_DRIVER_DEFAULT if your system uses ODBC and native drivers, and if you want the Netscape Application Server to choose between an ODBC driver and a native driver at connection time.
props.
IGXValList of connection-specific information required to log in to the data source. Use the following keys for the connection parameters:
ppConn.
A pointer to the created IGXDataConn object. When the extension is finished using the object, call the Release( ) method to release the interface instance.
Usage
A data connection is a communication link or session with a database or other data source. Before interacting with a data source, an extension must first establish a connection with it. Each connection is represented by a data connection object, which contains all the information needed to communicate with a database or data source, such as the name of the database, database driver, user name, password, and so on. A data connection object is an instance of the IGXDataConn interface.
Use GXContextCreateDataConn( ) to set up a separate connection for each database or data source you want to access. Extensions refer to the data connection object in their methods that perform subsequent operations on the database.
Rules
Tips
Return Value
HRESULT, which is set to GXE_SUCCESS if the function succeeds.
Example
// Method to open a connection to a database
STDMETHODIMP
CEmployeeMgr::GetOBDataConn(IGXDataConn **ppConn)
{
HRESULT hr=GXE_SUCCESS;
// Create a vallist for the connection parameters
IGXValList *pList=GXCreateValList();
if(pList) {
// Set up the connection parameters
GXSetValListString(pList, "DSN", OB_DSN);
GXSetValListString(pList, "DB", "");
GXSetValListString(pList, "USER", OB_USER);
GXSetValListString(pList, "PSWD", OB_PASSWORD);
// Attempt to create the connection
hr = GXContextCreateDataConn(m_pContext, 0, GX_DA_DRIVER_DEFAULT,
pList, ppConn);
// Release pList when it's no longer needed
pList->Release();
}
return hr;
}
GXContextCreateDataConnSet( )
Creates a collection used to dynamically assign query name/data connection pairs before loading a query file.
Syntax
HRESULT GXContextCreateDataConnSet(
IGXContext *pContext,
DWORD flags,
IGXDataConnSet **ppDataConnSet);
pContext.
A pointer to an IGXContext object, which provides access to Netscape Application Server services. Specify m_pContext if accessing this helper function from a manager class; otherwise, use m_pModule->m_pContext.
flags.
Specify 0. Internal use only.
ppDataConnSet.
Pointer to the created IGXDataConnSet object. When the extension is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use GXContextCreateDataConnSet( ) only if you are loading a query file using GXContextLoadHierQuery( ). To use a query file, an extension first establishes a data connection with each database on which any queries will be run.
Next, the extension calls GXContextCreateDataConnSet( ) to create an IGXDataConnSet object, then populates this collection with query name / data connection pairs. Each query name in the collection matches a named query in the query file. IDataConnSet provides a method for adding query name / data connection pairs to the collection. In this way, extensions can use standardized queries and select and assign data connections dynamically at runtime.
Finally, the extension calls GXContextLoadHierQuery( ) to create the hierarchical query object.
Return Value
HRESULT, which is set to GXE_SUCCESS if the function succeeds.
Related Topics
GXContextLoadHierQuery( )
GXContextCreateHierQuery( )
Creates a new query object used for building and running a hierarchical query.
Syntax
HRESULT GXContextCreateHierQuery(
IGXContext *pContext,
IGXHierQuery **pHQ);
pContext.
A pointer to an IGXContext object, which provides access to Netscape Application Server services. Specify m_pContext if accessing this helper function from a manager class; otherwise, use m_pModule->m_pContext.
pHQ.
A pointer to the created IGXHierQuery object. When the extension is finished using the object, call the Release( ) method to release the interface instance.
Usage
A hierarchical query can be more complex than a flat query. A hierarchical query combines one or more flat queries which, when run on the database server, returns a result set with multiple nested levels of data. The number of nested levels is limited only by system resources.
The hierarchical query is not necessarily a single query. In fact, a hierarchical query is a collection of one or more flat queries arranged in a series of cascading parent-child, one-to-many relationships. The parent query obtains the outer level of information, or summary, and the child query obtains the inner level of information, or detail. The parent level of information determines the grouping of information in its child levels. The child query is run multiple times, once for each row in the parent query's result set.
Tips
Return Value
HRESULT, which is set to GXE_SUCCESS if the function succeeds.
Example
// Create the hierarchical query
IGXHierQuery *pHq=NULL;
if(((hr=GXContextCreateHierQuery(m_pContext, &pHq))
==GXE_SUCCESS)&&pHq) {
// Add a query
pHq->AddQuery(pQuery, pConn, "SelCusts", "", "");
Related Topics
GXContextCreateDataConn( )
GXContextCreateQuery( )
GXContextCreateMailbox( )
Creates an electronic mailbox object used for communicating with a user's mailbox.
Syntax
HRESULT GXContextCreateMailbox(
IGXContext *pContext,
LPSTR pHost,
LPSTR pUser,
LPSTR pPassword,
LPSTR pUserAddr,
IGXMailbox **ppMailbox);
pContext.
A pointer to an IGXContext object, which provides access to Netscape Application Server services. Specify m_pContext if accessing this helper function from a manager class; otherwise, use m_pModule->m_pContext.
pHost.
Address of POP and SMTP server, such as mail.myOrg.com. If the POP and SMTP servers are running on different hosts, you must use two separate GXContextCreateMailbox( ) calls.
pUser.
Name of user's POP account, such as jdoe.
pPassword.
Password for POP server.
pUserAddr.
Return address for outgoing mail, such as john@myOrg.com. Usually the electronic mail address of the user sending the message.
ppMailbox.
Pointer to the created IGXMailbox object. When the extension has finished using the object, call its Release( ) method to release the interface instance.
Usage
Use GXContextCreateMailbox( ) to set up a mail session for sending and receiving electronic mail messages.
In the Internet electronic mail architecture, different servers are used for incoming and outgoing messages.
Rules
Tip
Once instantiated, use the methods in the IGXMailBox interface to open and close a mailbox, as well as send and receive mail messages.
Return Value
HRESULT, which is set to GXE_SUCCESS if the function succeeds.
GXContextCreateQuery( )
Creates a new query object used for building and running a flat query.
Syntax
HRESULT GXContextCreateQuery(
IGXContext *pContext,
IGXQuery **ppQuery);
pContext.
A pointer to an IGXContext object, which provides access to Netscape Application Server services. Specify m_pContext if accessing this helper function from a manager class; otherwise, use m_pModule->m_pContext.
ppQuery.
A pointer to the created IGXQuery object. When the extension is finished using the object, call the Release( ) method to release the interface instance.
Usage
A flat query is the simplest type of query. It retrieves data in a tabular, non-hierarchical result set. Unlike a hierarchical query, a flat query returns a result set that is not divided into levels or groups.
An extension can also use GXContextCreateQuery( ) to create a query object to perform SELECT, INSERT, DELETE, or UPDATE operations on a database.
Tips
Return Value
HRESULT, which is set to GXE_SUCCESS if the function succeeds.
Example
// Create a query to insert data into a table
IGXQuery *pUserQuery=NULL;
if(((hr=GXContextCreateQuery(m_pContext,
&pUserQuery))==GXE_SUCCESS)&&pUserQuery) {
pUserQuery->SetSQL("INSERT INTO OBUser(userName, password, userType,
eMail) VALUES (:userName, :password, :userType, :eMail)");
Related Topics
GXContextCreateDataConn( )
GXContextCreateQuery( )
GXContextCreateTrans( )
Creates a new transaction object used for transaction processing operations on a database.
Syntax
HRESULT GXContextCreateTrans(
IGXContext *pContext,
IGXTrans **ppTrans);
pContext.
A pointer to an IGXContext object, which provides access to Netscape Application Server services. Specify m_pContext if accessing this helper function from a manager class; otherwise, use m_pModule->m_pContext.
ppTrans.
A pointer to the created IGXTrans object. When the extension is finished using the object, after a call to either Commit( ) or Rollback( ), call the Release( ) method to release the interface instance.
Usage
Transaction processing allows the extension to define a series of database operations that succeed or fail as a group. If all operations in the group succeed, then the system commits, or saves, all of the modifications from the operations. If any operation in the group fails for any reason, then the extension can roll back, or abandon, any proposed changes to the target table(s).
If your application requires transaction processing, use GXContextCreateTrans( ) to create a transaction object. Pass this transaction object to subsequent methods, such as AddRow( ) or ExecuteQuery( ), that make up a transaction.
Tips
Return Value
HRESULT, which is set to GXE_SUCCESS if the function succeeds.
Example
// Create a transaction for several insert operations
IGXTrans *pTx=NULL;
if(((hr=GXContextCreateTrans(m_pContext, &pTx))==GXE_SUCCESS)&&pTx) {
// Begin the transaction
pTx->Begin();
IGXResultSet *pRset=NULL;
// Update User
if(((hr=pUserPQuery->Execute(0, pUserValList, pTx, NULL,
&pRset))==GXE_SUCCESS)&&pRset) {
// The result set is not needed; release it
pRset->Release();
// Update Customer
if(((hr=pCustPQuery->Execute(0, pCustValList, pTx, NULL,
&pRset))==GXE_SUCCESS)&&pRset) {
// All updates succeeded. Commit the transaction
pTx->Commit(0, NULL);
GXSetValListString(pValIn, "ssn", m_pSsn);
GXSetValListString(pValIn, "OUTPUTMESSAGE", "Successfully
updated customer record");
if(GXContextNewRequest("AppLogic CShowCustPage", pValIn,
pValOut, 0)!=GXE_SUCCESS)
HandleOBSystemError("Could not chain to CShowCustPage
AppLogic");
}
else {
pTx->Rollback();
HandleOBSystemError("Could not insert checking account record
for new customer");
}
}
else {
pTx->Rollback();
HandleOBSystemError("Could not insert checking account record for
new customer");
}
pTx->Release();
}
else
HandleOBSystemError("Could not start transaction");
GXContextDestroySession( )
Deletes a user session.
Syntax
HRESULT GXContextDestroySession(
IGXContext *pContext,
LPSTR pAppName,
LPSTR pSessionID,
IGXSessionIDGen *pIDGen);
pContext.
A pointer to an IGXContext object, which provides access to Netscape Application Server services. Specify m_pContext if accessing this helper function from a manager class; otherwise, use m_pModule->m_pContext.
pAppName.
Name of the application associated with the session. The application name enables the Netscape Application Server to determine which extensions have access to the session data.
pSessionID.
The session ID to use.
pIDGen.
The session ID generation object used to generate session IDs. Specify NULL to use the default IGXSessionIDGen object, or specify a custom session ID generation object.
Usage
To increase security and conserve system resources, use GXContextDestroySession( ) to delete a session between a user and the application when the session is no longer required. An extension typically calls GXContextDestroySession( ) when the user logs out of an application.
Tip
If the extension set a timeout value for the session when it was created, you need not delete the session explicitly with GXContextDestroySession( ). The session is deleted automatically when the timeout expires.
Return Value
HRESULT, which is set to GXE_SUCCESS if the function succeeds.
GXContextGetAppEvent( )
Retrieves the application event object.
Syntax
HRESULT GXContextGetAppEvent(
IGXContext *pContext,
IGXAppEvent **ppAppEvent);
pContext.
A pointer to an IGXContext object, which provides access to Netscape Application Server services. Specify m_pContext if accessing this helper function from a manager class; otherwise, use m_pModule->m_pContext.
ppAppEvent.
A pointer to the retrieved IGXAppEvent object. When the extension is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use GXContextGetAppEvent( ) to retrieve an IGXAppEvent object. Through the IGXAppEvent interface, you can create and manage application events. An extension uses application event objects to define events that are triggered at a specified time or times or when triggered explicitly.
Return Value
HRESULT, which is set to GXE_SUCCESS if the function succeeds.
GXContextGetObject( )
Retrieves an object from the context.
Syntax
HRESULT GXContextGetObject(
IGXContext *pContext,
LPSTR service
IID iid
LPVOID *ppObj);
pContext.
A pointer to an IGXContext object, which provides access to Netscape Application Server services. Specify m_pContext if accessing this helper function from a manager class; otherwise, use m_pModule->m_pContext.
service.
Name of the service in the context to retrieve.
iid.
Identifier of the interface sought on the service.
ppObj.
Returned service object. If the returned object is an IGXObject, then call Release( ) when done with the service object.
Usage
Call GXContextGetObject to retrieve a service (from another extension, for example), in order to access the services of another loaded extension.
Return Value
HRESULT, which is set to GXE_SUCCESS if the function succeeds.
Example
// Get the data access engine object from the context
IGXObject *pObj=NULL;
HRESULT hr;
hr=GXContextGetObject(m_pContext,
"IID_IGXModuleData",
IID_IGXModuleData,
(LPVOID *)&pObj);
GXGetStateTreeRoot( )
Returns an existing root node of a state tree or creates a new one.
Syntax
HRESULT GXGetStateTreeRoot(
IGXContext *pContext,
DWORD dwFlags,
LPSTR pName,
IGXState2 **ppStateTree)
pContext.
A pointer to an IGXContext object, which provides access to Netscape Application Server services. Specify m_pContext if accessing this helper function from a manager class; otherwise, use m_pModule->m_pContext.
dwFlags.
Specify one of the following flags or zero to use the default settings:
pName.
The name of the root node. If a node with this name doesn't already exist, a new node is created.
ppStateTree.
A pointer to the created IGXState2 object. When the extension is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use GXGetStateTreeRoot( ) to create a state tree. A state tree is a hierarchical data storage mechanism. It is used primarily for storing application data that needs to be distributed across server processes and clusters.
Return Value
HRESULT, which is set to GXE_SUCCESS if the function succeeds.
Example
The following code shows how to create a state tree and a child node:
HRESULT hr;
hr = GXGetStateTreeRoot(m_pContext, GXSTATE_DISTRIB|GXSTATE_PERSISTENT,
"Grammy", &m_pStateRoot);
if (hr == NOERROR && m_pStateRoot)
{
IGXState2 *pState = NOERROR;
hr = m_pStateRoot->GetStateChild("Best Female Vocal",
&pState);
if (hr != NOERROR || !pState)
{
hr = m_pStateRoot->CreateStateChild("Best Female Vocal",
0, GXSTATE_DISTRIB|GXSTATE_PERSISTENT, &pState);
GXContextIsAuthorized( )
Checks a user's permission level to a specified action.
Syntax 1
Use in most cases.
HRESULT GXContextIsAuthorized(
IGXContext *pContext,
LPSTR pTarget,
LPSTR pPermission,
DWORD *pResult);
Syntax 2
Contains several parameters that are place holders for future functionality.
HRESULT GXContextIsAuthorized(
IGXContext *pContext,
LPSTR pDomain,
LPSTR pTarget,
LPSTR pPermission,
DWORD method,
DWORD flags,
IGXCred *pCred,
IGXObject *pEnv,
DWORD *pResult);
pContext.
A pointer to an IGXContext object, which provides access to Netscape Application Server services. Specify m_pContext if accessing this helper function from a manager class; otherwise, use m_pModule->m_pContext.
pDomain.
The type of Access Control Lists (ACL). An ACL (created by the server administrator) defines the type of operations, such as Read or Write, that a user or group can perform. There are two types of ACLs: AppLogic and general. For this parameter, specify one of the following strings, which specifies the type of ACL to check for this user:
"kiva:acl,logic"
"kiva:acl,general"
pTarget.
The name of the ACL, if the ACL is a general type. If the ACL is an AppLogic ACL, specify the AppLogic name or GUID string.
pPermission.
The type of permission, for example, "EXECUTE."
method.
Specify 0.
flags.
Specify 0.
pCred.
Specify NULL.
pEnv.
Specify NULL.
pResult.
Pointer to the client-allocated variable that contains the returned permission status. The variable is set to one of the following enum constants:
Usage
Use GXContextIsAuthorized( ) in portions of the code where application security is enforced through Access Control Lists (ACL). This function lets an application check if a user has permission to execute an AppLogic or perform a particular action. The application can use the result of GXContextIsAuthorized( ) as a condition in an If statement. It can, for example, return a message to users who are denied access to an AppLogic.
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.
Return Value
HRESULT, which is set to GXE_SUCCESS if the function succeeds.
Example
DWORD auth_result = 0;
if (GXContextIsAuthorized("Shop_Inventory", "WRITE", &auth_result) !=
NOERROR || auth_result != (DWORD) GXACL_ALLOWED)
{
GXContextLog("Unauthorized access: Shop_Inventory");
return GXE_FAIL;
}
else
// Update inventory
GXContextLoadHierQuery( )
Creates a hierarchical query by loading a query file containing one or more query names and associated data connections.
Syntax
HRESULT GXContextLoadHierQuery
IGXContext *pContext,
LPSTR pFileName,
IGXDataConnSet *pDataConnSet,
DWORD flags,
IGXValList *pParams,
IGXHierQuery **ppHierQuery);
pContext.
A pointer to an IGXContext object, which provides access to Netscape Application Server services. Specify m_pContext if accessing this helper function from a manager class; otherwise, use m_pModule->m_pContext.
pFileName.
Name of the query (.GXQ) file, including the path. Use a relative path when possible.
A query file is an ASCII text file containing one or more SQL statements. You can create the file using any ASCII text editor. Use the following syntactical guidelines:
pDataConnSet.
Collection of query name/data connection pairs. The query names in the collection must match the named queries in the query file. The associated IDataConn object identifies the data connection for the query.
flags.
Specify 0 (zero). Internal use only.
pParams.
IGXValList of query file parameters, or NULL. A collection of place holders for the WHERE clause. A place holder may be a name or a number. It is prefixed by a colon (:) character. The place holders can be replaced by specifying replacement values in the ValList parameter.
ppHierQuery.
Pointer to the created IGXHierQuery object. When the extension is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use GXContextLoadHierQuery( ) to create a hierarchical query object. An extension can retrieve standardized queries stored in a data file and, at runtime, can dynamically select and assign the data sources on which the query is run. You create the query file separately using the Netscape Application Builder query editor window or an ASCII text editor, ANSI 89 standard SQL SELECT statements, and specialized Netscape Application Server syntax. A query file can define both flat and hierarchical queries.
To use a query file, the extension first establishes a data connection with each database on which any queries will be run. Next, the extension calls GXContextCreateDataConnSet( ) to create an IGXDataConnSet collection, then populates this collection with query name / data connection pairs. Each query name in the collection matches a named query in the query file.
IGXDataConnSet provides a method for adding query name / data connection pairs to the collection. In this way, extension can use standardized queries and assign data connections dynamically at runtime. Finally, the extension calls GXContextLoadHierQuery( ) to create the hierarchical query object.
Rules
Return Value
HRESULT, which is set to GXE_SUCCESS if the function succeeds.
Example
The following example shows a query (GXQ) file and a section of an extension that loads the hierarchical query file and creates an HTML report:
Query file:
/* STATES */
query STATES using (ODBC, kstates, kuser) is
select STATES.STATE as STATES_STATE
from STATES
where (STATES.REGION = ':REGION')
order by STATES.STATE asc
/* DETAILS */
query DETAILS using (ODBC, kdetails, kuser) is
select COUNTIES.COUNTYNAM as COUNTIES_COUNTYNAM,
COUNTIES.POP as COUNTIES_POP,
COUNTIES.STATE as COUNTIES_STATE
from COUNTIES
order by COUNTIES.COUNTYNAM asc
join DETAILS to parent STATES
where DETAILS.COUNTIES.STATE = 'STATES.STATES_STATE'
Extension code snippet:
IGXDataConnSet *connSet = NULL;
HRESULT hr;
hr = GXContextCreateDataConnSet(m_pContext, 0, &connSet);
if (hr == GXE_SUCCESS)
{
// Create database connections
IGXDataConn *conn_detailDB = NULL;
IGXDataConn *conn_statesDB = NULL;
IGXValList *pList=GXCreateValList();
pList->SetValString("DSN", "kdetails");
pList->SetValString("DB", "");
pList->SetValString("USER", "kuser");
pList->SetValString("PSWD", "kpassword");
// Create first connection
hr = GXContextCreateDataConn(m_pContext, 0, GX_DA_DRIVER_DEFAULT,
pList,
NULL, &conn_detailDB);
if (hr == GXE_SUCCESS)
{
pList->SetValString("DSN", "dstates");
pList->SetValString("DB", "");
pList->SetValString("USER", "kuser");
pList->SetValString("PSWD", "kpassword");
// Create second connection
hr = GXContextCreateDataConn(m_pContext, 0, GX_DA_DRIVER_DEFAULT,
pList,
NULL, &conn_statesDB);
pList->Release();
if (hr == GXE_SUCCESS)
{
// Specify query / db connection pairs
connSet->AddConn("DETAILS", conn_detailDB);
connSet->AddConn("STATES", conn_statesDB);
// Create IGXValList that contains the
// REGION parameter value to pass to the
// hierarchical query
IGXValList param = GXCreateValList();
param->SetValString("REGION", "WEST");
IGXHierQuery *hqry;
// Load the GXQ file with the db connection set
// and parameter value
hr = GXContextLoadHierQuery(m_pContext, "state.gxq", connSet,
0,
param, &hqry);
if (hr == GXE_SUCCESS)
{
// Run the report ....
}
Related Topics
GXContextCreateDataConnSet( )
GXContextLoadQuery( )
Creates a flat query by loading a query file.
Syntax
HRESULT GXContextLoadQuery(
IGXContext *pContext,
LPSTR pFileName,
LPSTR pQueryName,
DWORD flags,
IGXValList *pParams,
IGXQuery **ppQuery);
pContext.
A pointer to an IGXContext object, which provides access to Netscape Application Server services. Specify m_pContext if accessing this helper function from a manager class; otherwise, use m_pModule->m_pContext.
pFileName.
Name of the query (.GXQ) file, including the path. Use a relative path when possible.
A query file is an ASCII text file containing one or more SQL statements. You can create the file using any ASCII text editor. Use the following syntactical guidelines:
pQueryName.
Name of the query in the query file.
flags.
Specify 0 (zero). Internal use only.
pParams.
IGXValList of query file parameters, or null. A collection of place holders for the WHERE clause. A placeholder may be a name or a number. It is prefixed by a colon (:) character. The place holders can be replaced by specifying replacement values in the IGXValList parameter.
ppQuery.
Pointer to the created IGXQuery object. When the extension is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use GXContextLoadQuery( ) to create a flat query object by loading a query (.GXQ) file. An extension can retrieve standardized queries stored in a data file and, at runtime, can dynamically select and assign the data source on which the query is run.
You create the query file separately using the Netscape Application Builder query editor window or an ASCII text editor, ANSI 89 standard SQL SELECT statements, and special Netscape Application Server syntax.
To run the flat query, call ExecuteQuery( ) in the IGXDataConn interface.
Return Value
HRESULT, which is set to GXE_SUCCESS if the function succeeds.
Example
The following example shows a query (GXQ) file and a section of an extension that loads and executes the query:
Query file:
/* STATES */
query STATES using (ODBC, kstates, kuser) is
select STATES.STATE as STATES_STATE
from STATES
where (STATES.REGION = ':REGION')
order by STATES.STATE asc
Extension code snippet:
HRESULT hr;
// Create database connection
IGXDataConn *conn = NULL;
IGXValList *pList=GXCreateValList();
pList->SetValString("DSN", "kstates");
pList->SetValString("DB", "");
pList->SetValString("USER", "kuser");
pList->SetValString("PSWD", "kpassword");
hr = GXContextCreateDataConn(m_pContext, 0, GX_DA_DRIVER_DEFAULT,
pList,
NULL, &conn);
if (hr == GXE_SUCCESS)
{
// Create IGXValList that contains the REGION
// parameter value to pass to the
// hierarchical query
IGXValList param = GXCreateValList();
param->SetValString("REGION", "WEST");
IGXQuery *qry;
// Load the GXQ file with the parameter value
hr = GXContextLoadQuery(m_pContext, "state.gxq", "STATES", 0,
param, &qry);
// Execute the query
IGXResultSet *rs = NULL;
hr = conn->ExecuteQuery(GX_DA_RS_BUFERRING, qry, NULL,
NULL, &rs);
GXContextLog( )
Writes a log message to an output device.
Syntax 1
Logs a message (type = GXEVENTTYPE_INFORMATION and category = 0).
HRESULT GXContextLog(
IGXContext *pContext,
LPSTR msg);
Syntax 2
Logs an event with a message, specifying the type and category of event.
HRESULT GXContextLog(
IGXContext *pContext,
DWORD type,
DWORD category,
LPSTR msg);
pContext.
A pointer to an IGXContext object, which provides access to Netscape Application Server services. Specify m_pContext if accessing this helper function from a manager class; otherwise, use m_pModule->m_pContext.
msg.
Message text to log.
type.
Message type. Use one of the following variables:
category.
User-defined message category. Do not use the range of values reserved for the Netscape systems, which is 0 to 65535, inclusive.
Usage
Use GXContextLog( ) for displaying or storing simple messages or for debugging. The output can be directed to the console, to a text file, or to a database table. To direct output, use the Netscape Application Server Administrator. For more information, see the Administration Guide.
Return Value
HRESULT, which is set to GXE_SUCCESS if the function succeeds.
Example
hr = GXContextGetSession(m_pContext, 0, "Catalog", NULL, &m_pSession);
if (hr != GXE_SUCCESS)
{
GXContextLog(m_pContext, "Could not get session; creating a new
one");
hr = GXContextCreateSession(m_pContext, GXSESSION_DISTRIB, 0, NULL,
NULL, NULL, &m_pSession);
GXContextNewRequest( )
Calls an AppLogic.
Syntax 1
Passes in the specified IGXValList of input parameters and result values. The location of the AppLogic execution depends on partitioning and load balancing criteria.
HRESULT GXContextNewRequest(
IGXContext *pContext,
LPSTR guid,
IGXObject *vIn,
IGXObject *vOut,
DWORD flag);
Syntax 2
Same as Syntax 1, but explicitly specifies the location of AppLogic execution.
HRESULT GXContextNewRequest(
IGXContext *pContext,
LPSTR guid,
IGXObject *vIn,
IGXObject *vOut,
DWORD host,
DWORD port,
DWORD flag);
pContext.
A pointer to an IGXContext object, which provides access to Netscape Application Server services. Specify m_pContext if accessing this helper function from a manager class; otherwise, use m_pModule->m_pContext.
guid.
String GUID or name of the AppLogic to execute.
vIn.
IGXValList object containing input parameters to pass to the called AppLogic.
vOut.
IGXValList object containing result values of the called AppLogic.
host.
IP address of the Internet host of the Netscape Application Server where the AppLogic is to be executed. Specify 0 to execute the AppLogic locally.
port.
Internet port of the Netscape Application Server where the AppLogic is to be executed. Specify 0 to execute the AppLogic locally.
flag.
Specify zero.
Usage
Use GXContextNewRequest( ) to call an AppLogic. When you call GXContextNewRequest( ), the extension passes to the Netscape Application Server the GUID or name of the AppLogic to execute and, optionally, any input and output parameters.
Netscape Application Server constructs a request using the parameters specified and processes it like any other request, by instantiating the AppLogic and passing in its parameters. The results from the called AppLogic module are returned to the calling extension.
The AppLogic that GXContextNewRequest( ) invokes can do one of the following tasks:
If the called AppLogic uses EvalOutput( ) to stream results, EvalOutput( ) returns HTML results by default. The caller can, however, specify that EvalOutput( ) return a non-HTML data stream by setting the gx_client_type key to "ocl" in the input IGXValList of GXContextNewRequest( ). For example:
vallist.SetValString("gx_client_type", "ocl");
Rule
The specified GUID string, input parameters, and output parameters must be valid for the specified AppLogic.
Tips
Return Value
HRESULT, which is set to GXE_SUCCESS if the function succeeds.
GXContextNewRequestAsync( )
Calls another AppLogic and runs it asynchronously.
Syntax 1
Passes in the specified IGXValList of input parameters and result values. The location of the AppLogic execution depends on partitioning and load balancing criteria.
HRESULT GXContextNewRequestAsync(
IGXContext *pContext,
LPSTR guid,
IGXObject *vIn,
IGXObject *vOut,
DWORD flag,
IGXOrder **ppOrder);
Syntax 2
Same as Syntax 1, but explicitly specifies the location of AppLogic execution.
HRESULT GXContextNewRequestAsync(
IGXContext *pContext,
LPSTR guid,
IGXObject *vIn,
IGXObject *vOut,
DWORD host,
DWORD port,
DWORD flag
IGXOrder **ppOrder);
pContext.
A pointer to an IGXContext object, which provides access to Netscape Application Server services. Specify m_pContext if accessing this helper function from a manager class; otherwise, use m_pModule->m_pContext.
guid.
String GUID or name of the AppLogic to execute.
vIn.
IGXValList object containing input parameters to pass to the called AppLogic.
vOut.
IGXValList object containing result values of the called AppLogic.
host.
IP address of the Internet host of the Netscape Application Server where the AppLogic is to be executed. Specify 0 to execute the AppLogic locally.
port.
Internet port of the Netscape Application Server where the AppLogic is to be executed. Specify 0 to execute the AppLogic locally.
flag.
Specify 0.
ppOrder.
Pointer to the returned IGXOrder object, which the caller can use to obtain the status of the request. When the caller is finished using the order object, call the Release( ) method to release the interface instance.
Usage
Use GXContextNewRequestAsync( ) to call another AppLogic and run it asynchronously. Executing an AppLogic asynchronously is useful if the AppLogic performs a lengthy operation, or if the AppLogic acts as a monitor or remains persistent. For example, an asynchronous AppLogic may perform a lengthy database query to produce a complex result set that it e-mails to a destination address. Another AppLogic module may run continuously and re-index HTML pages every 24 hours.
When an extension calls GXContextNewRequestAsync( ), it passes to the Netscape Application Server the GUID of the AppLogic module to execute and, optionally, any input and output parameters.
The Netscape Application Server constructs a request using the parameters specified and processes it like any other request, by instantiating the AppLogic and passing in its parameters. The results from the called AppLogic module are returned to the calling code.
The AppLogic that GXContextNewRequestAsync( ) invokes can do one of the following tasks:
Rules
Tips
Return Value
HRESULT, which is set to GXE_SUCCESS if the function succeeds.
Example
IGXOrder *pOrder;
ULONG nOrder;
HRESULT hr, ReqResult;
if (GXContextNewRequestAsync(m_pContext, asyncGUIDStr, m_pValIn,
m_pValOut, 0, &pOrder) == GXE_SUCCESS)
{
GXContextLog(m_pContext, "Successfully invoked async AppLogic\n");
// wait for async AppLogic to finish (max 100 seconds)
hr = GXWaitForOrder(&pOrder, 1, &nOrder, m_pContext, 100);
if (hr != NOERROR)
{
return hr;
}
else
{
pOrder->GetState(NULL, &ReqResult, NULL);
if (ReqResult != NOERROR)
return ReqResult;
}
}
else
{
GXContextLog(m_pContext,
"Failed to invoke async AppLogic\n");
}
|
Previous
