Beginning execution of the connector

When the connector is started, the connector framework instantiates the associated connector class and then calls the connector class methods in Table 52.

Table 52. Beginning execution of the connector

Initialization task For more information
1. Initialize the connector's application-specific component to perform any necessary initialization for the connector, such as opening a connection to the application. "Initializing the connector"
2. For each business object that the connector supports, obtain the business object handler. "Obtaining the C++ business object handler"

Initializing the connector

To begin connector initialization, the connector framework calls the initialization method, init(), in the connector class, (derived from GenGlobals). This method performs initialization steps for the connector's application-specific component.

Important:
As part of the implementation of your connector class, you must implement an init() method for your connector.

As discussed in "Initializing the connector",, the main tasks of the init() initialization method include:

In addition to the above topics, this section provides an example C++ init() method in "Example C++ initialization method".

Important:
During execution of the initialization method, business object definitions and the connector framework's subscription list are not yet available.

Establishing a connection

The main task of the init() method is to establish a connection to the application. It returns "success" if the connector succeeds in opening a connection. If the connector cannot open a connection, the init() method must return the appropriate failure status to indicate the cause of the failure. In a C++ connector, typical return codes used in init() are BON_SUCCESS, BON_FAIL, and BON_UNABLETOLOGIN. For information on these and other return codes, see "Handling errors and status".

Note:
For an overview of the steps in an initialization method, see "Establishing a connection".

Checking the connector version

The getVersion() method returns the version of the connector's application-specific component.

Note:
For a general description of getVersion(), see "Checking the connector version".

In the C++ connector library, the getVersion() method is defined in the GenGlobals class. It returns a pointer to a character string indicating the version of the connector. When returning a version string for the connector, you can choose to return the default version as defined by the connector framework. To do this, return the string CX_CONNECTOR_VERSIONSTRING, as shown in Figure 54 below.

Figure 54. A getVersion() method for a C++ connector

char * ExampleGenGlob::getVersion()
{
   return (char *) CX_CONNECTOR_VERSIONSTRING;
}

Alternatively, you can override the default version by setting a version string in a file named ConnectorVersion.h. Include the following lines, or something similar, in ConnectorVersion.h.

#ifndef CX_CONNECTOR_VERSIONSTRING
#define CX_CONNECTOR_VERSIONSTRING    "3.0.0"
#endif

Recovering In-Progress events

To recover In-Progress events, a C++ connector must use whatever technique the application provides to access event records in the event store. For example, the connector could use the ODBC API and ODBC SQL commands. Once the In-Progress event record has been retrieved, the connector can take one of the actions in Table 23 to handle the In-Progress event.

Note:
For a general discussion of how to recover In-Progress events, see "Recovering In-Progress events".

Example C++ initialization method

For a C++ connector, the init() method provides the initialization for the connector's application-specific component. This method returns an integer that indicates the status of the initialization operation. Figure 55 shows an example of the initialization method for a C++ connector. In this example, the init() method calls GenGlobals::getConfigProp() to retrieve the properties of the connector configuration from the repository. The connector's application-specific component uses the configuration values to log on to the application and perform any other required initialization tasks.

Figure 55. Initializing a C++ connector

int ExampleGenGlob::init(CxVersion *version)
{
   char val[512];
   char val1[512];
 
   int return_code = BON_SUCCESS;
 
   // get values for connector configuration properties 
   getConfigProp("ConnectorName", val, 512);
   //Log trace message "Initializing {ConnectorName}"
   traceWrite(Tracing::LEVEL5, generateMsg(20050,
            CxMsgFormat::XRD_INFO, NULL, 1, val), NULL);
 
   . . .
   getConfigProp("Hostname",val1, 512);
 
   // use configuration values to log in to the application
   // If log in fails, log error message. 
   logMsg(generateMsg(21000,CxMsgFormat::XRD_ERROR, NULL, 1, name));
 
   return return_code;
}

Obtaining the C++ business object handler

In a C++ connector, the business-object-handler base class is BOHandlerCPP. To obtain an instance of a business object handler for a supported business object, the connector framework calls the getBOHandlerforBO() method, which is defined as part of the GenGlobals class.

Note:
For general information about the getBOHandlerforBO() method, see "Obtaining the business object handler". For a general discussion of how to design business object handlers, see "Designing business object handlers".

The number of business object handlers that the connector framework obtains through its calls to the getBOHandlerforBO() method depends on the overall design for business object handling in your connector:

Important:
During execution of the getBOHandlerforBO() method, the business-object class methods are not yet available.

Figure 56 calls the constructor for the GenBOHandler class to instantiate a single business object handler class that handles all the business objects supported by the connector.

Figure 56. A getBOHandlerforBO() method for a generic business object handler

BOHandlerCPP *ExampleGenGlob::getBOHandlerforBO(char * BOName)
{
   //   If a business object handler does not exist,
   //   create one; otherwise, return the existing pointer
   if(pHandlr == NULL) {
      pHandlr = new GenBOHandler();
   }
   return pHandlr;
}

Figure 57 calls the constructor for the appropriate business object handler, based on the business object name that is passed in:

Copyright IBM Corp. 1997, 2004