This article provides a guideline on troubleshooting display corruptions through the adjustment of Citrix Multi-Monitor Hook API.

Background

MMHook has developed over time to include many function calls and hooks for various functionalities, scenarios, Windows operating system, code changes and so on. Consequently, in default form it includes hooks which are not used in all scenarios. While it is tested with a variety of hardware configurations, it is not viable to ensure the default implementation functions 100% with all operating system/hardware/application combinations.

While Multiple Monitors might not be in use, the MMHook DLL is always injected into each application’s API, in case it is needed. Because all applications and display drivers function slightly different, it is not possible to write generic code which will be 100% successful. As a result, MMHook can sometimes cause display corruptions.

Consequently, the components which are not core to the functionality are configurable to allow MMHook to be adapted in situations where there are conflicts, or where certain Function Calls fail to access/hook into the display process correctly or fails completely. This is achieved through configurable Registry Values. For explanation of the configuration process refer to CTX115637 – Citrix Multi-Monitor Configuration Settings and Reference, which details the workings of MMHook and the available adjustments.

This article explains how the information in CTX115637 can be used to identify if MMHook is responsible for a display corruption; and how the in-built adjustments may be used to either create a workaround or identify the conflicting component.

Troubleshooting Display Corruption with Multi-Monitor Hook

To determine if MMHook might be interfering with the display of an application, complete the following tests:

• Enabling/Disabling MMHook

• MMHook Adjustments

Important:

• Tests should be performed on an isolated XenApp Server which is not Load Balancing a copy of the production application.

• Test the application after each change, and undo each change before trying the next one. If multiple changes are tested simultaneously, it will not be possible to identify a single root cause.
  For details on the MMHook Settings Configuration, see CTX115637 – Citrix Multi-Monitor Configuration Settings and Reference.

Enabling/Disabling MMHook

Caution! Refer to the Disclaimer at the end of this article before using Registry Editor.

1. Rename the value in the following registry entry to prevent MMHook from loading entirely:
   HKLM\Software\Citrix\CtxHook\AppInit_dlls\Multiple Monitor Hook\FilePathName
   That is, change the value from c:\Program Files\Citrix\System32\mmhook.dll to c:\Program Files\Citrix\System32\mmhook_test.dll.
   Re-test the application.

2. Allow MMHook to load, but disable it for all applications.
   Create the following DWORD registry entry with a data value of 0, (zero):
   HKLM\Software\Citrix\CtxHook\AppInit_dlls\Multiple Monitor Hook\DefaultHooks 
   Re-test the application.

3. Exclude the problematic application from MMHook by creating a REG_SZ (String Value) Registry Entry with data value of ProcessName.exe, where ProcessName.exe is the name of the executable for the application.
   HKLM\Software\Citrix\CtxHook\AppInit_dlls\Multiple Monitor Hook\
   Value Name: Exclude
   Type: REG_SZ (String Value)
   Value Data: ProcessName.exe

   Note: ProcessName is case sensitive (case sensitivity of the process name is determined by viewing the process names from within Task Manager).
   Re-test the application.

4. If the application begins to function correctly after any of the preceding MMHook adjustments, then the following step depends on whether the application will be used in a Multi Monitor situation:

   • If No, then permanently exclude the application from MMHook.

   • If Yes, then adjust the MMHook to verify if configuration adjustments can lead to compatibility. Refer to the following section for this procedure.

MMHook Adjustments

1. If MMHook is identified as causing the conflict, it is possible that a configurable sub-component might be causing the issue. There are core hooks which are always enabled with MMHook. However, some sub-components can be enabled or disabled using an additional Reg Value.
   For details on the MMHook Settings Configuration, refer to CTX115637 – Citrix Multi-Monitor Configuration Settings and Reference.
   Create a DWORD Reg value named DefaultHooks in the location: HKLM\Software\Citrix\CtxHook\AppInit_dlls\Multiple Monitor Hook .

2. Assign this key various decimal values, one after the other, to try and identify if one particular hook causes this issue or the core MMHooks are causing this issue. Values are contained in CTX115637 – Citrix Multi-Monitor Configuration Settings and Reference.
   Start with the total value of all the Hooks summed together, such as: 131071 (this means that all the Hooks are enabled). Then, subtract the value of each Hook and re-test.
   Example:
   First test: DefaultHooks=131071
   Second test: 131071-65536 (value for FORCEMAXIMIZETOMONITOR) => DefaultHooks = 65535
   And so on.

3. If a Hook is found which when disabled resolves the issue then try taking the total or all enabled value again (131071) and only subtracting the value of the problem hook.
   If the application functions normally, without any lost functionality with this hook disabled, then this will be the new configuration. If this change reduces some functionality, a case must be logged with Citrix Support. Providing the conflicting Hook will help Citrix to focus their analysis.

   Note: For XenApp 6.0 or later, the only configurable individual Hook is LAUNCHONMONITORHOOK. (Decimal 2048 / Hex 0x800),  refer to CTX115637 – Citrix Multi-Monitor Configuration Settings and Reference for more information.