2
Tool Palette and Menu Integration

This chapter covers the Tool palette and menu interface. It describes:

Integrating an Application into the Console

The Oracle Enterprise Manager Console allows you to register and launch an application directly from a tool palette or a pull-down menu. If you have registered an application in the NT registry, the Console uses registration information to make an application available to Console users. The Console can:

Launch an application from a palette or menu.
Launch an application and pass it connection details from the selected service or node.

In order for Oracle Enterprise Manager to know about an application, you must register it in the NT registry. When the Console starts up, it reads the registry and looks for applications that are to be made available in the Console.

To have the Console simply launch an application, you need to register an application in the NT registry. See Registering an Application with the Console on page 2-2.
To have the Console pass an application connection details, you must either implement a SetLogonInfoEx OLE automation interface or process the command line parameters that Oracle Enterprise Manager passes if you are using a non-OLE automation server. See Passing Contextual Information to an OLE Automation Server Application on page 2-8 or Passing Contextual Information to a non-OLE Automation Server Application on page 2-8.

Registering an Application with the Console

To register an application with the Enterprise Manager Console, entries must be made into the NT registry. Each application must define a unique application key under the HKEY_CLASSES_ROOT\OracleSmpConsole\Applications key. To avoid naming collisions with applications developed by other companies, you should begin the name of all of the application keys with a substring uniquely identifying your company. All of the details that the Console needs to know about the application should be placed underneath its application key. The syntax for an application's NT registration keys is:

HKEY_CLASSES_ROOT\OracleSmpConsole\Applications\AppNameKey\regkey = 
regkeyvalue

where:

OracleSmpConsole\Applications identifies the application as one that should be displayed in the Console. This is the specific location where the Enterprise Manager Console looks for all registered applications.
AppNameKey, such as Smpsrv, is the key that is used by the NT Registry to organize the subkeys that relate to the application. This key is also used by the Console internally to refer to an application.
regkey, such as ExeType, is one of registration keys.
regkeyvalue, such as OLE_AUTOMATION, is a registration key value.

Figure 2-1, "Example of an NT Registry" shows a sample NT registry. It includes an entry for the SmpSrv test application registered with the Console. For a complete example of the keys used to register an application in the registry, see the smpsrv.reg file.

Figure 2-1 Example of an NT Registry

The Console uses an application's registration information to:

Gather details relating to how the application should be launched.
Determine the application's National Language Support (NLS) name.
Display an application's icon in the appropriate tool palette.
Include a menu item for an application in the appropriate submenu of the Tool menu.

Required Registration Keys

To register an application with the Enterprise Manager, you must specify the following four keys:

The application key: The internal name for the application.
Name: The readable application name key, with NLS subkeys.
Executable: The executable filename.
ExeType: The executable type. Application Key

The value of the application key is the string that is used internally by the Console to identify the application. Both the application key and value must be unique. For example:

HKEY_CLASSES_ROOT\OracleSmpConsole\Applications\OEMSample = 

OEMSample

Note:

Make sure that there are no spaces trailing the application key string because these spaces are considered part of the key value.

Readable Name

This is the name displayed by the Console in the Tools menu. The name is also displayed in bubble help and status bar help for the palette. All readable strings that Oracle Enterprise Manager requires to be specified in the registry, including the application names, handle national language translation in the same way. The Name key's value is the default name for the application, which should be in American English. The console will use this string if it is running in a language for which no NLS subkey has been specified. For example:

HKEY_CLASSES_ROOT\OracleSmpConsole\Applications\OEMSample\Name = 

OEMSample Application

For every language the application can support, an NLS subkey, or language code, should be specified. For example, the Japanese name would include JA instead of US in the registration key syntax. For a list of the subkeys, see Appendix A, "NLS Codes". The value of a subkey is the name of the application in the appropriate language. For example:

HKEY_CLASSES_ROOT\OracleSmpConsole\Applications\OEMSample\Name\US = 

OEMSample Application

Executable Filename

The executable name of the application. The executable itself must be installed in either your ORACLE_HOME\BIN subdirectory or within the current path. If the executable is located anywhere else, the application will fail to appear in the tool palettes and menus you desire. The executable file name should be supplied without path information. For example:

HKEY_CLASSES_ROOT\OracleSmpConsole\Applications\OEMSample\Executable = 

SMPSRV.EXE
Executable Type

The type of executable file. The executable type can be one of the values listed in Table 2-1, "Executable Types".

Table 2-1 Executable Types

Value	Meaning	Comments
OLE_AUTOMATION	OLE Server	Overwhelmingly recommended. Must implement SetLogonInfoEx interface
EXEC	Simple executable	Simple launch without context
EXEC_PARAMS	Command line launch-in-context	Same context info as in SetLogonInfoEx, but passed on the command line

For example:

HKEY_CLASSES_ROOT\OracleSmpConsole\Applications\OEMSample\ExeType = 

OLE_AUTOMATION

Additional steps that are necessary to launch each of the executable types are discussed in following sections of this chapter.

Optional Registration Keys

There are several optional keys that each application can specify: the Palettes, Types, CLSID, and Icon keys. Oracle recommends that you specify Palettes and Type. CLSID is required to register an OLE Automation server application.

Palettes

This key determines the list of palettes where the application is displayed, usually only one. Multiple entries are separated by commas. Use of the Palettes key is optional but strongly recommended. Define this key to specify on which Tools Palette the application will appear within the console.

If you list a particular Tools Palette, the application's icon will appear, and its (NLS) name will appear in Tooltips and status bar help when the mouse lingers over that icon for a brief period of time. In addition, there will be a corresponding menu item included in the appropriate location in the Tools menu.

Tools palettes are specified by their internal names. Multiple tools palettes can be specified: the value of the "Palettes" key should be a comma separated list. For example:

HKEY_CLASSES_ROOT\OracleSmpConsole\Applications\OEMSample\Palettes = 

OracleApps,SampleApps

There is a default tool palette whose internal name is OracleApps. Its external name is simply Applications, which is generic enough that most applications can be put there. It is also possible to define your own tool palette. See Defining a Custom Tool Palette on page 2-10.

Types

This key determines the types of objects that this application administers. If you specify the Types key, the application will appear in the Related Tools contextual menu for all the types you list in the key's value. Types are specified by their internal type name. Multiple entries are separated by commas. For example:

HKEY_CLASSES_ROOT\OracleSmpConsole\Applications\OEMSample\Types = 

DATABASE,NODE,LISTENER

Types specified can be those defined by Oracle Enterprise Manager itself as they appear in the header file voxtype.h, or can be those which you or another third-party vender define as external service types. See Chapter 5, "Navigator and Map Integration".

Related Tools menus pop up when you click the right mouse button on an object in the Navigator. A list of applications which are appropriate to the administration of objects of that type appear as a submenu. Selection of one of these applications launches it with the context of the selected object.

CLSID

To register an OLE Automation server application, one additional registry key is required, the CLSID key. Specify the CLSID of the OLE server as the value of this key. For example:

HKEY_CLASSES_ROOT\OracleSmpConsole\Applications\OEMSample\CLSID = 

{FC2B0F50-0036-11CF-BEF1-0020AF0C14D1}

The server must implement and expose the SetLogonInfoEx interface to receive launch-in-context information.

Icon

To change the icon that an application uses in the tool palette, use the Icon key. The replacement icon must be stored in bitmap format (*.bmp). For example:

HKEY_CLASSES_ROOT\OracleSmpConsole\Applications\OEMSample\Icon = 

%oracle_home%\sysman\admin\vaxtpdus.bmp

If an icon is not found for an application, a default icon (oracle_home\sysman\admin\vaxtpdus.bmp) is automatically used. This default icon is also used if an integrated application is not an MFC application and its executable does not contain an icon. The tbicon.reg file in the oracle_home\sysman\sdk directory currently points to the default icon.

Credential Precedence

Part of the context of an application's launch is the logon credentials for the service that is associated with the selected object in the Navigator tree or on the Map. These credentials include the username and password, plus role if the object selected is a database service. The role specifies how to connect to the database: NORMAL, SYSOPER, or SYSDBA. The Console allows an individual user to specify preferred credentials for any service, including those defined externally by third parties. For information, see Chapter 5, "Navigator and Map Integration".

Also, at any given time it may be possible to be connected to a service within the console under arbitrary credentials entered in a Login Information dialog. Accordingly, the precedence of the credentials which will be sent as context is determined according to the following rules:

If the user has already explicitly connected to the service, the arbitrary credentials entered in a Login Information dialog or the preferred credentials at the time of connection are sent.
If a user has not entered arbitrary credentials and has defined a preferred credential for the service, these are sent.
If a user has not entered arbitrary credentials and has not defined a preferred credential for the service, the current console logon credentials are sent.

Passing Contextual Information to an OLE Automation Server Application

When the Console launches an OLE automation application, it calls the application's SetLogonInfoEx automation interface, if such an interface has been defined in the application. See SetLogonInfoEx on page 2-11.

Note:

If an application is a non-OLE automation server, the Console can still pass logon information if you have specified the ExecType = EXEC_PARAMS.

The Console passes the following connection information to the application:

Credentials of the Console user for the node or service selected in the navigator.
Object name and type selected in the Navigator or Map.

OLE Launching Considerations

The application must be an OLE server and must be able to launch with the OLE Open verb. If the application is going to support external service types described in Chapter 5, "Navigator and Map Integration", it should also be able to launch with the CreateDispatch method.

Passing Contextual Information to a non-OLE Automation Server Application

If the ExeType for an application is specified to be EXEC_PARAMS, contextual information about the currently selected object in the Navigator tree or on the Map will be passed to the application via the command line. An example of specifying EXEC_PARMS is:

HKEY_CLASSES_ROOT\OracleSmpConsole\Applications\OEMSample\ExeType = 

EXEC_PARMS

Seven named parameters separated by spaces are passed on the command line according to the following syntax:

paramter_name=value

The meanings of each of these parameters are described in Table 2-2, "Command-Line Parameters".

Table 2-2 Command-Line Parameters

Parameter name	Meaning	Notes
user	Username of service related to selected object	Defaults according to credential precedence rules.
password	Password of service related to selected object	Defaults according to credential precedence rules.
service	Name of service related to selected object	For example: If the selected object is a tablespace, the related service would be the database that tablespace is a part of.
type	Type of service related to selected object	Internal service type name, either from voxtype.h, or defined externally.
as	Connect as role, for databases only.	Only values are SYSOPER or SYSDBA. If NORMAL or service is not a database, this parameter is not supplied.
object	Name of selected object
objecttype	Type of selected object	Internal type name, either from voxtype.h, or defined externally.

Defining a Custom Tool Palette

You can define custom tool palette to put applications on. However, because tool palettes look awkward if they have less than three applications on them, you should do this only if you have three or more applications in an application suite which you choose to integrate. If you have less than three applications to place on a palette, consider using the OracleApps palette. For information on specifying a palette, see Optional Registration Keys on page 2-5.

To create a custom palette, you only need to specify an internal name for the new palette and the human readable name, with NLS subkeys. The internal name is the keyword which will appear in the Palettes key for each application you want to place on your palette. The human readable name will be used in the title bar of the undocked palette, and will also be used to create a new entry under the Tools menu in the console to correspond to the new palette.

Registering a Custom Palette

To create a new tool palette that will appear in the Console, you need to add an internal name, external name, and NLSkey to the NT Registry. These entries are added under the HKEY_CLASSES_ROOT\OracleSmpConsole\Palettes key.

Internal Name

Internal palette name.The name must be a unique subkey to represent the palette you are registering. For example:

HKEY_CLASSES_ROOT\OracleSmpConsole\Palettes\SampleApps = 

SampleApps
External Name

Default value for human readable name (US English). For example:

HKEY_CLASSES_ROOT\OracleSmpConsole\Palettes\SampleApps\Name = 

Sample Applications
NLSkey

NLS value for human readable name. For example:

HKEY_CLASSES_ROOT\OracleSmpConsole\Palettes\SampleApps\Name\US = 

Sample Applications

After you have included the palette in the registry, you can add an application to it as described Registering an Application with the Console on page 2-2.

API Reference

In order for an OLE application to receive connection information from the Console, the application must expose a SetLogonInfoEx method.

Note:

If you do not expose a SetLogonInfoEx method an application will still launch, but no credentials will be passed.

SetLogonInfoEx

Purpose

SetLogonInfoEx allows the Console to pass the Console user's credentials and the selected object name to an application. It should have the following syntax:

Syntax

VT_EMPTY SetLogonInfoEx(VTS_BSTR Username, 

                VTS_BSTR Password, 

                VTS_BSTR Service, 

                VTS_BSTR ServiceType, 

                VTS_BSTR ConnectAs, 

                VTS_BSTR FocusedObectName, 

                VTS_BSTR FocusedObjectType)

Parameters

Name	Type	Mode
Username	VTS_BSTR	IN
Password	VTS_BSTR	IN
Service	VTS_BSTR	IN
ServiceType	VTS_BSTR	IN
ConnectAs	VTS_BSTR	IN
FocusedObjectName	VTS_BSTR	IN
FocusedObjectType	VTS_BSTR	IN

Username

Username for the service that defines an application's launching context.

Password

Password for the service that defines an application's launching context.

Service

Name of the service or node that defines the context an application is being launched in by the Console.

ServiceType

Type of service that defines the context an application is being launched in by the Console. For information on type parameters, see Discovery Cache API Reference on page 6-5.

ConnectAs

Role to be used when connecting to the database. Values are NORMAL, SYSOPER, or SYSDBA. The value is NORMAL if the ServiceType is not a database.

StrFocusedObject

Name of the focused object in the Navigator or Map.

TypeFocusedObject

Type of the focused object in the Navigator or Map.

Comments

Enterprise Manager calls SetLogonInfoEx function to pass contextual information about the service. After the application has obtained this information from the Console, it can use that information to open a connection to a service.

If the current selection in the Navigator is a container, the FocusedObjName parameter will be an empty string and the FocusedObjType parameter will contain the type for that container. If the container appears under a service in the tree, that service will appear in the Service and Type fields, and the Username, Password, and ConnectAs credentials will be those which are in force for that service as determined by the credential precedence scheme discussed above. If the container does not appear under a service, the Service name will be the empty string, the Type field will be VOXTYPE_TYPE_INVALID, and the credentials will be the console logon credentials.

2Tool Palette and Menu Integration

Integrating an Application into the Console

Registering an Application with the Console

Figure 2-1 Example of an NT Registry

Required Registration Keys

Note:

Readable Name

Table 2-1 Executable Types

Optional Registration Keys

Palettes

Types

CLSID

Icon

Credential Precedence

Passing Contextual Information to an OLE Automation Server Application

Note:

OLE Launching Considerations

Passing Contextual Information to a non-OLE Automation Server Application

Table 2-2 Command-Line Parameters

Defining a Custom Tool Palette

Registering a Custom Palette

Internal Name

API Reference

Note:

SetLogonInfoEx

Purpose

Syntax

Parameters

Username

Password

Service

ServiceType

ConnectAs

StrFocusedObject

TypeFocusedObject

Comments

2
Tool Palette and Menu Integration