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.