Understanding and Troubleshooting Chappfile and LockfileEx Errors in Hyperion Enterprise

Understanding and Troubleshooting Chappfile and LockfileEx Errors in Hyperion Enterprise
		Modified 11-FEB-2011     Type FAQ

---

Applies to:

Hyperion Enterprise - Version: 5.1.1.0.00<max_ver> and later   [Release: 5.1 and later ]
Information in this document applies to any platform.
This knowledge document is a replacement for 585407.1 which has been deleted.

Purpose

This document has been written to guide customers through resolving issues of reoccurring CHappfile and LockfileEx error messages; it covers Hyperion Enterprise 5/6 File-Based applications without Hyperion's Data Server Service. Readers of this document should familiarize themselves with the Hyperion Enterprise Release Notes Release 5.x/6.x This document should be read first and fully understood before proceeding.

Questions and Answers

What is a CHappfile Error? 

CHappfile errors, which are recorded in the Hyperion Enterprise application's error.log file, are written by Hyperion Enterprise whenever a file access problem occurs, either for Read or Write. For example, in the event the server or the server service is restarted and workstations are connected with open files, all files opened by the workstation on the server are closed. In this situation, the workstation still has file handles associated with files on the server, but the server has lost its associated file handles. The file handles on the workstation are now invalid and can no longer be used to update files on the server. Error messages can only be written to the error.log if the client is able to re-establish connection to the server and open the error.log. 

Causes of CHappfile Errors :

CHappfile error messages can be traced back to various environmental factors. CHappfile messages do not always indicate the application has integrity issues, but they do indicate some type of disconnects are occurring. CHappfile messages are normally written to the application Error.log file, provided that the client can still connect to the server. If the client cannot connect to the server to write the message, then a pop up message may appear on the client or no message is recorded. The location of the Error.log is based on the User_Path setting in the HYPENT.INI file. It is possible to have multiple Error.log files if users have modified their HYPENT.INI file. 

Examples of CHappfile Errors :

The following are examples of CHappfile errors: 

• CHappfile::ReadFromSysFile returned: Reached end of file.

• Error reading free blocks : CPropFileIO::GetFreeArea  (This is not a CHappfile message but this message has been found in the midst of other CHappfile messages.)

• CHappfile::WriteToFile returned: Reached end of file.

• CHappfile::ReadFromSysFile returned: The handle is invalid.

• CHappfile::WriteToFile returned: The process cannot access the file because another process has locked a portion of the file.

• CHappfile::ReadFromSysFile returned: The operation completed successfully.

• CHappfile::ReadFromSysFile returned: The specified network name is no longer available.

• CHappfile::ReadFromSysFile returned: Cannot create a file when that file already exists.

Possible messages written to client workstation System Event logs: 

• Event ID 3009 "The redirector failed to unlock part of a file on server Hyperion_Enterprise_Server_Name."

• Event ID 26 Application popup: System Process - Lost Delayed-Write Data : The system was attempting to transfer file data from buffers to \\Hyperion_Enterprise_Server_Name\Share\551demo\551demo.EXA. The write operation failed, and only some of the data may have been written to the file.

Interpreting Error.log entries :

When reviewing the Error.log file, it is important to understand this file is an event log as well as an error log. Not all events in the application are logged, but some informational events like consolidation start and complete times, data load and extract start and complete times, report previews and retrieve refreshes are logged. 

When reviewing the Error.log file, here is a sample of what may be found: 

(User: admin ) An unrecoverable error occurred. 
LockFileEx returned: Time=8:30:11 PM 3/5/02, OS Error Code=0x6, OS Error Message= The handle is invalid. , Module=N:\Hyperion Solutions\Hypent.exe Terminating current session. 

This sample comes from version 5.x/6.x, which includes additional error logging information. 
The key items to note are the OS Error Code and the OS Error Message. The OS Error Code is what has been returned to the Hyperion Enterprise application. The OS Error Message gives the text meaning of that OS Error Code (Prove this to yourself: on a Windows machine open a Command prompt and type 'net helpmsg'. The text return should be The handle is invalid.) These are not Hyperion program errors but are OS errors being reported to Enterprise. 

Prior to 5.x/6.x, here is a sample of the same event: 

(User: admin ) An unrecoverable error occurred. 
LockFileEx returned: The handle is invalid. 
Terminating current session. 

The additional information provided by 5.x/6.x and later versions also includes the Module the user was in and the time the error was reported to the Enterprise program. The time listed does not necessarily mean that the underlying problem occurred at this time. 
For example, if a user is logged into Enterprise and steps away from their computer and the Enterprise file server is rebooted for some reason, no error will be reported by that user's Enterprise program until they return to the workstation and attempt to access the application files. The time stamp of the error could be several hours after the server reboot caused the disconnect. 

What is a LockFileEx Error? 

Like CHappfile errors, LockFileEx Errors recorded in the Hyperion Enterprise application's error.log file indicate that Hyperion Enterprise experienced a problem reading or writing to a file. LockFileEx messages are normally written to the application Error.log file provided that the client can still connect to the server. If the client cannot connect to the server to write the message, then a pop up message may appear on the client or no message is recorded. Also, like CHappfile messages, LockFileEx messages do not always indicate the application has integrity issues, but they do indicate some type of network disconnects happening. 

Examples of common LockFileEx messages found in the Error.log: 

• LockFileEx returned: The session was cancelled.

• LockFileEx returned: The handle is invalid.

• LockFileEx returned: An unexpected network error occurred.

• LockFileEx returned: The specified network name is no longer available.

Possible messages written to client workstation System Event logs: 

Event ID 3013. The redirector has timed out a request to Hyperion_Enterprise_Server_Name. 




Current Recommendations :


Please refer first to the Hyperion Enterprise 5/6 Release Notes.
The release notes for version 5.5 and later include Appendix A, which listed Suggested Network Guidelines for Hyperion Enterprise. 
The following information should be considered to complement those sections. Before making any changes to your production environment it is recommended that the changes be fully tested on a non-production system that closely matches the production environment. 




Basic environmental recommendations:


These are standard recommendations that should apply to all environments: 

• Network Interface Cards (NIC) and switch ports should not be set for Auto Sensing of Speed and Duplex method. These devices should be configured to match both speed and duplex method.

• Running Hyperion Enterprise on Domain Controllers is not recommended

• Clustering technologies like MSCS should not be used in Active mode

• Backups and file copies should not be made with users in an application

• Virus scanning should not be configured to scan the Enterprise application data files in Real-time mode

• All Windows servers and workstations should be on the same Service pack level.

Hyperion Enterprise Servers Windows and Windows (file servers): 

• Disable Opportunistic Locking at the server service level
  
  • Add the following Value:
    \HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\LanmanServer\Parameters
    Value Name: EnableOplocks 
    Data Type: REG_DWORD 
    Value (decimal): 0 
    
    
• Disable Remote File Control Blocks (RFCB) caching
  
  • Add the following Value:
    \HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\LanmanServer\Parameters 
    Value Name: CachedOpenLimit 
    Data Type: REG_DWORD 
    Value (decimal): 0 
    

Windows Terminal Services (with or without Citrix): 

For Windows servers running Terminal Service, the article Q299603 was found to list a few registry modifications to help resolve redirector problems. Although the error mentioned 'Error reading file' is not seen in Enterprise, the registry changes are being recommended as part of the standard troubleshooting process. 

From Q299603: 

• Disable Opportunistic Locking at the workstation/redirector level
  
  • Add the following Value:
    \HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Mrxsmb\Parameters 
    Value Name: OpLocksDisabled 
    Data Type: REG_DWORD 
    Value (decimal): 1 
    

• Disable File caching
  
  • Add the following Value:
    \HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\LanmanWorkstation\Parameters 
    Value Name: UtilizeNTCaching 
    Data Type: REG_DWORD 
    Value (decimal): 0
    

• Disable Remote File Control Blocks (RFCB) caching
  
  • Add the following Value:
    \HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\LanmanServer\Parameters 
    Value Name: CachedOpenLimit 
    Data Type: REG_DWORD 
    Value (decimal): 0 
    

Windows 2000:

For the specific errors 'CHappfile::ReadFromSysFile returned: An unexpected network error occurred'. or 'LockFileEx returned: An unexpected network error occurred' when Windows Terminal servers are involved, apply the hotfix Q320310 if using SP1 or SP2. Service Pack 3 for Windows also includes the fixes to address the 'unexpected network error'. Q320310 is a Pre-SP3 Hotfix Q320310 includes the updated files fromQ272582. 

If any Windows machines are found to be Blue Screening, you must address those machines first. The proper way to handle Blue Screening workstations is to contact Microsoft. You can determine the type of Stop error from the System Event Log. Common errors on Profession machines are Stop 0x1E and Stop 0xA. These are Kernel level Microsoft driver issues and not the result of a Hyperion Enterprise process. Search Microsoft's Knowledge database for the specific stop error being reported for an applicable Hotfix(s). 

For Windows servers running Terminal Services, Dr. Watson errors occurring while navigating the Enterprise desktop may be resolved by disabling Dr. Watson. The Advanced Concepts MetaFrame XPhas a section on Dr. Watson were it states you should either run the application compatibility scripts or you can disable Dr. Watson all together. Q188296 list the registry keys. 

• To disable Dr. Watson 
  
  • Totally, clear the following value:
    \HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\AeDebug
    Value Name: Debugger 
    Data Type: REG_SZ 
    Value: (blank) 
    

The application.ini file settings are as follows:


SETTING
LOG
APP_USELOGGING = 1
Log option is switched on
APP_LOGFILECREATION=1
Logs createfile and closehandle
APP_LOGFILEREAD=1
Logs all reads
APP_LOGFILEWRITE=1
Logs all writes
APP_LOGFILELOCKS=1
Logs all lock and unlock
APP_LOGFILEALL=1
Logs all file i/o/locks/operationsf
APP_SESSTIMEOUT_INTERVAL=30000
# of milliseconds for the application to timeout a lock request (this is to handle the issue with the sesstimeout and the NT redirector)

LOGGING SAMPLE:
(User: USER ) : ReadFile:lpFileName=D:\ENT61\61Apps\demo\Demo.EXA, lpBuffer=0x12da04, nNumberOfBytesToRead=3248, lpNumberOfBytesRead=3248, retCode=1, OS Return Code=0x0

(User: USER ) : CreateFile:lpFileName=D:\ENT61\61Apps\demo\Demo.LOK, dwDesiredAccess=-1073741824, dwShareMode=3, dwCreateDisposition=4, dwFlagsAndAttributes=0x50000080, hObject=0xee00a4, OS Return Code=0x0

APP_SESSION_TIMEOUT
APP_SESSION_TIMEOUT in the app.ini file is set to 15000ms less than the registry sesstimeout value (default 45 s). The application system lock timeout is controlled by the APP_SESSION_TIMEOUT. This setting forces the application to intercept system lock request (LockFileEx) before it is timed out by the NT file redirector (controlled by sesstimeout). This setting is only applicable to Windows NT or 2000 operating systems.