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" |
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.
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".
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".
The getVersion() method returns the version of the connector's application-specific component.
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
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.
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; }
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.
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:
Figure 56 contains an implementation of the getBOHandlerforBO() method that returns a metadata-driven business object handler. It calls the constructor for the business-object-handler class (derived from the GenBOHandler class), which instantiates a single business-object-handler class that handles all the business objects supported by the connector.
Figure 57 contains an implementation of the getBOHandlerforBO() method that creates unique business object handlers for Invoice and Item business objects, and creates a generic business object handler for all other business objects.
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:
Figure 57. A getBOHandlerforBO() method for multiple business object handlers
BOHandlerCPP *ExampleGenGlob::getBOHandlerforBO(char * BOName) { if (strcmp(BOName, App_Invoice)==0) return new Invoice_Handler(); else if (strcmp(BOName, App_Item)==0) return new Item_Handler(); else return new Generic_Handler(); } }