3
General Coding Techniques

This chapter covers the general coding techniques for writing an application. Topics include:

• Console Service Objects
• Initializing and Disposing Dispatch Drivers
• Retrieving Error Information
• VoxErrorUnpacker Class and Methods

Console Service Objects

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:

1. Get the document's IUnknown.
2. Find out the class ID (CLSID) from the document object's ProgID.
3. Register this object as the active one.

For an example illustrating how to initialize and register the Smpsrv document object, see CSmpsrvDoc::CSmpsrvDoc in the smpsrdoc.cpp file.

Initializing and Disposing Dispatch Drivers

The following steps allow an application to call Enterprise Manager's external interfaces:

1. Use the service's ProgID to get the class ID (CLSID).
2. Ask IUnknown to get the active object of that class.
3. Call QueryInterface to get the IDispatch of the service.
4. Attach the 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.

The Job Object

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.

Retrieving Error Information

Most of the functions in the Enterprise Manager external interfaces return a VT_BOOL.

• A TRUE value indicates that the function has succeeded.
• A FALSE value indicates failure.

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

Purpose

GetErrorInfo retrieves error information about the API which was executed last for a particular OLE service.

Syntax

VT_VARIANT GetErrorInfo()

Comments

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.

Note:

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.

VoxErrorUnpacker Class and Methods

The class VoxErrorUnpacker has several methods which help you to unpack the error information from the VARIANT returned by GetErrorInfo.

• GetErrorText
• GetErrorCause
• GetErrorData
• Success
• Failure

Note:

The class definition for VoxErrorUnpacker is in the file voxerr.h.

GetErrorText

Purpose

Call the GetErrorText method to extract the text from the VARIANT returned by GetErrorInfo.

Syntax

const CString& GetErrorText()

Comments

GetErrorText returns a string which contains the error text.

GetErrorCause

Purpose

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.

Syntax

long GetErrorCause()

Comments

GetErrorCause returns a LONG number which represents a specific error.

GetErrorData

Purpose

Call the GetErrorData method to get other error data from the VARIANT returned by GetErrorInfo.

Syntax

const VARIANT& GetErrorData()

Comments

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.

Note:

Not all errors have associated data.

Success

Purpose

Call the Success method to determine if an API function succeeded or not.

Syntax

BOOL Success()

Comments

Success returns a BOOLEAN that determines whether the called API function succeeded: TRUE for success and FALSE for failure.

Failure

Purpose

Call the Failure method to determine if an API function failed or not.

Syntax

BOOL Failure()

Comments

Failure returns a BOOLEAN that determines whether the called API function failed: TRUE for failure and FALSE for success.

---