Release 1.4.0
A53701_01
 Library |
 Product |
 Contents |
 Index |
| Oracle Enterprise Manager Application Developer's Guide Release 1.4.0 A53701_01 |
|
This chapter covers the general coding techniques for writing an application. Topics include:
The Oracle Enterprise Manager Console contains an OLE2 Automation Service object which exposes all of its external APIs, except those pertaining to job submission. The ProgID for this service is OracleSmpConsole. The Console starts up this service upon initialization, and then declares it to be the active object of its OLE class. As there can only be one console running at a time, it is guaranteed that there will be one and only one object of this class. You should use the MFC call GetActiveObject to retrieve a dispatch interface for the OracleSmpConsole object. You can then use this interface to call any of the automation methods described in this guide. For an example of the use of GetActiveObject, see CSmpSrvDlg::GetDispatchDriver in the smpsrvdl.cpp file.
If you are integrating tightly into the console; which means most of the application's functionality requires the console's back-end services; then you will want to try to connect to the OracleSmpConsole service when the application initializes. If this connection fails, you should display a message informing the user that the application requires the Oracle Enterprise Manager to be running and then abort the application.
In order for the Enterprise Manager Console to use the various interfaces that an application exposes, you must initialize an OLE automation server object, usually the application's document object, and register it as the active object. To do this:
IUnknown.
CLSID) from the document object's ProgID.
For an example illustrating how to initialize and register the Smpsrv document object, see CSmpsrvDoc::CSmpsrvDoc in the smpsrdoc.cpp file.
The following steps allow an application to call Enterprise Manager's external interfaces:
ProgID to get the class ID (CLSID).
IUnknown to get the active object of that class.
QueryInterface to get the IDispatch of the service.
LPDISPATCH to a COleDispatchDriver and return the dispatch driver.
For an example illustrating how to create and initialize a dispatch driver to use in calling the Oracle Enterprise Manager external interfaces, see CSmpSrvDlg::GetDispatchDriver in the smpsrvdl.cpp file.
When you are done with a dispatch driver you should dispose of it. For an example illustrating how to how to dispose a dispatch driver, see CSmpSrvDlg::ReleaseDispatchDriver in the smpsrvdl.cpp file.
Every time you want to submit a new job or delete an existing one, you must create a new OLE automation object of the class OracleSmpJob. An easy way to do this is to use the MFC call CreateDispatch. You then initialize the job and perform whatever manipulations you desire. The OracleSmpJob object gets destroyed when you are done. This method differs fundamentally from that of using any of the other APIs, where you call GetActiveObject on the OracleSmpConsole service which always exists and runs with the console.
For an example illustrating how to use CreateDispatch, see CSmpSrvDlg::GetJobObject in the smpsrvdl.cpp file.
Most of the functions in the Enterprise Manager external interfaces return a VT_BOOL.
Whenever an API fails, call GetErrorInfo to retrieve more information about the failure. Every OLE automation object in the Enterprise Manager Console implements its own GetErrorInfo interface.
GetErrorInfo retrieves error information about the API which was executed last for a particular OLE service.
VT_VARIANT GetErrorInfo()
This function returns a VARIANT that contains the specific error information for the interface function that failed. Use the helper functions described in the section VoxErrorUnpacker Class and Methods on page -5 to unpack the error information.
You may call GetErrorInfo even if the function succeeded.
For an example illustrating how to use GetErrorInfo to retrieve error information and use the VoxErrorUnpacker class to unpack that information, see CSmpSrvDlg::DoGetErrorInfo in the smpsrvdl.cpp file. The dispatch driver varies according to the OLE service you want to request the error information for.
The class VoxErrorUnpacker has several methods which help you to unpack the error information from the VARIANT returned by GetErrorInfo.
The class definition for VoxErrorUnpacker is in the file voxerr.h.
Call the GetErrorText method to extract the text from the VARIANT returned by GetErrorInfo.
const CString& GetErrorText()
GetErrorText returns a string which contains the error text.
Call the GetErrorCause method to extract the error number from the VARIANT returned by GetErrorInfo. The semantics of these numbers will be dependent upon the function that failed.
long GetErrorCause()
GetErrorCause returns a LONG number which represents a specific error.
Call the GetErrorData method to get other error data from the VARIANT returned by GetErrorInfo.
const VARIANT& GetErrorData()
GetDataError returns a VARIANT that contains any other kind of data which was passed back. This data will depend on which function failed and what caused the error.
Not all errors have associated data.
Call the Success method to determine if an API function succeeded or not.
BOOL Success()
Success returns a BOOLEAN that determines whether the called API function succeeded: TRUE for success and FALSE for failure.
Call the Failure method to determine if an API function failed or not.
BOOL Failure()
Failure returns a BOOLEAN that determines whether the called API function failed: TRUE for failure and FALSE for success.
