External applications and dynamic link libraries

For the OnDemand Client, Content Manager OnDemand provides menu and toolbar extensions that allow a user to invoke another Windows application or execute a function in a Dynamic Link Library (DLL).

This facility is activated by placing information in the Windows system registry. During initialization, if Content Manager OnDemand detects this information, it adds menu items and toolbar buttons. When the user chooses one of these menu items or clicks one of these toolbar buttons, Content Manager OnDemand invokes the associated application or calls the associated entry point in a DLL.

Content Manager OnDemand reads the HKEY_CURRENT_USER\Software\IBM\OnDemand32\Client\ExternalApps or HKEY_LOCAL_MACHINE\Software\IBM\OnDemand32\Client\ExternalApps key in the Windows system registry for the following keys and string values:

Table 1. External Applications and Dynamic Link Library Keys in the Registry. Value Names and Value Data for external applications and Dynamic ink Library Keys in the registry.
Key	Value Name	Value Data
ExternalApps	Apps	`a1`[,`a2`][,`a3`][,`a4`][,`a5`]
`a1`	Path	application path
	MenuText	menu item text
	BitmapDLL	toolbar button bitmap DLL path
	BitmapResid	toolbar button bitmap resource identifier
	Folders	folder name[\folder name]…
	ExcludeFolders	folder name[\folder name]…
	Doc	0 \| 1 \| 2 \| 3
	CopyDoc	ASIS \| ASCII
	Parameter	parameter data
ExternalDlls	Dlls	`d1`[,`d2`][,`d3`][,`d4`][,`d5`]
`d1`	Path	DLL path
	Function	function name
	MenuText	menu item text
	BitmapDll	toolbar button bitmap DLL path
	BitmapResid	toolbar button bitmap resource identifier
	Folders	folder name[\folder name]…
	ExcludeFolders	folder name[\folder name]…
	Doc	0 \| 1 \| 2 \| 3
	CopyDoc	ASIS \| ASCII
	Parameter	parameter data

A maximum of five applications and five DLLs are specified. The DLLs can be divided between the HKEY_CURRENT_USER and HKEY_LOCAL_MACHINE keys. The key names can be any string. The values, which must be string values, are interpreted as follows:

Path: Specifies the path for the application or DLL. This value must be provided and should be fully-qualified or in the execution path.
Function: Specifies the name of an entry point in the DLL specified with Path. This value must be provided for a DLL. It is not relevant for an application.
MenuText: Specifies the text to appear on the associated menu item under the Content Manager OnDemand Window menu. This value is optional. If not provided, the menu item is blank.
BitmapDLL: Specifies the path for a DLL containing a bitmap resource to be used for a toolbar button to be associated with the application or DLL. This DLL can be the same as or different from any DLL specified for a Path DLL or another BitmapDLL DLL. The bitmap should be 16 pels wide and 16 pels high.; This value is optional. If not provided, a toolbar button is not created.
BitmapResid: Specifies the resource id of the bitmap within the DLL specified for BitmapDLL. This value is ignored if BitmapDLL is not specified and optional if it is. If not provided, a value of 0 is assumed.
Folders: Specifies one or more names of Content Manager OnDemand folders. If multiple names are provided, they must be separated by a backslash (’\’) character. An asterisk (’*’) is used as a wildcard character in the last position of the name. This is equivalent to listing all folder names beginning with the characters preceding the asterisk.; The associated menu item, and corresponding toolbar button, is enabled whenever a document is being viewed and the folder associated with the active document is one of the specified folders, or a document is not being viewed and the current folder is one of the specified folders.; This value is optional.; If the ExcludeFolders value is provided, this value is ignored. If neither is provided, a folder name test is not performed before enabling the menu item and toolbar button.
ExcludeFolders: Specifies one or more names of Content Manager OnDemand folders. The syntax is the same as the Folders value.; The associated menu item, and corresponding toolbar button, is enabled whenever a document is being viewed and the folder associated with the active document is not one of the specified folders, or a document is not being viewed and the current folder is not one of the specified folders.; This value is optional. If not provided, enablement is controlled by the Folders value.
Doc: 0 indicates that enablement of the associated menu item and corresponding toolbar button is limited only by the Folders and ExcludeFolders values.; 1 indicates that the associated menu item and corresponding toolbar button is enabled only when a document is being viewed.; 2 indicates that the associated menu item and corresponding toolbar button is enabled only when a document list is being viewed and at least one document is selected.; 3 indicates that the associated menu item and corresponding toolbar button is enabled only when a document is being viewed or a document list is being viewed and at least one document is selected.; This value is optional. If not provided, a value of 3 is assumed.
CopyDoc: Indicates that a copy of one or more documents is to be provided to the external application or DLL and specifies the type of data to be provided. If the value is ASIS, the document data is in its native format. If the value is ASCII, the document data is converted to an ASCII file.; If the user chooses the associated menu item or corresponding toolbar button when a document is being viewed, the data provided is for the active document. If the folder document list is being displayed, the data is a concatenation of all documents selected in the document list.; This value is optional. If not provided, no document is provided to the external application or DLL.
Parameter: Specifies a maximum of 255 characters to be passed as parameter data to the external application or DLL. This value is optional. If not provided, no parameter data is passed to the external application or DLL.

The following three screens show an example of the required registry entries for External Applications.

This diagram illustrates External Applications in the Registry. — Figure 1. Example of External Applications in the Registry Part 1 of 3

The following two screens show an example of the required registry entries for External DLLs.

This diagram illustrates External DLLs in the Registry. — Figure 4. Example of External DLLs in the Registry Part 1 of 2

If the user chooses a menu item or clicks a toolbar button associated with an application, Content Manager OnDemand invokes the application with the command line:

application path /F folder /P page /T text /A attrvalue /D fields /N filename /R data

Where:

application path: The path specified with the Path value in the registry.
folder: The name of the active folder or, if a document is being displayed, the folder associated with that document. If no folder is open, the /F parameter is not provided.
page: The current page of the document being viewed. If no document is being viewed or if the active folder window is being displayed, the /P parameter is not provided.
text: The currently selected text in the document being viewed or the document list of the active folder. The format of the text is the same as that obtained by copying it to the clipboard. It can contain tab and newline characters. If no such text exists, the /T parameter is not provided.
attrvalue: The attribute/value pair associated with the current page of the document being viewed. The attribute and value are separated by a tab character. If no such attribute/value pair exists, the /A parameter is not provided.
fields: A set of folder field name/value pairs associated with the document being viewed. Each pair contains the name of a folder field and, separated by a tab character, the value of that field for the document. The pairs are separated by a newline character. If no such text exists, the /D parameter is not provided.
filename: The fully-qualified path and filename of document data as described for the CopyDoc registry entry. If the CopyDoc entry is not specified or no data is available, the /N parameter is not provided.
data: The parameter data specified for the Parameter registry entry. If the Parameter entry is not specified, the /R parameter is not provided.

If the user chooses a menu item or clicks a toolbar button associated with a DLL, Content Manager OnDemand calls the entry point (function) specified with the Function value in the registry. This function must be of the following type:

typedef void ( WINAPI * ArsExternalDllFunction )
                           ( long   page_number,
                             wchar_t * pFolderName,
                             wchar_t * pSelectedText,
                             wchar_t * pAttributeAndValue,
                             wchar_t * pFieldsAndValues,
                             wchar_t * pFilename,
                             wchar_t * pParameterData );

Where:

page_number: The current page of the document being viewed. If no document is being viewed or if the active folder window is being displayed, this value is 0.
pFolderName: A pointer to a null-terminated unicode string containing the name of the active folder or, if a document is being displayed, the folder associated with that document. If no folder is open, this value is NULL.
pSelectedText: A pointer to a null-terminated unicode string containing the currently selected text in the document being viewed or the document list of the active folder. The format of the text is the same as that obtained by copying it to the clipboard. It can contain tab and newline characters. If no such text exists, this value is NULL.
pAttributeAndValue: A pointer to a null-terminated unicode string containing the attribute/value pair associated with the current page of the document being viewed. The attribute and value are separated by a tab character. If no such attribute/value pair exists, this value is NULL.
pFieldsAndValues: A pointer to a null-terminated unicode string containing a set of folder field name/value pairs associated with the document being viewed. Each pair contains the name of a folder field and, separated by a tab character, the value of that field for the document. The pairs are separated by a newline character. If no such text exists, this value is NULL.
pFilename: A pointer to a null-terminated unicode string containing the fully-qualified path and filename of document data as described for the CopyDoc registry entry. If the CopyDoc entry is not specified or no data is available, this value is NULL.
pParameterData: A pointer to a null-terminated unicode string containing the parameter data specified for the Parameter registry entry. If the Parameter entry is not specified, this value can be NULL or point to an empty string.