Environment
Reflection Desktop version 16.0 or higher
Situation
A custom application that uses Reflection's WinHLLAPI interface fails to run. The Reflection HLLAPI trace log shows the following information:
WinHLLAPIStartup time entry 0
# Err: WinHllapi version negotiation failed.
< Return Code: 61444
time exit 0 Total Time(0)
# Err: WinHllapi version negotiation failed.
< Return Code: 61444
time exit 0 Total Time(0)
Resolution
Use the following C# declarations for Reflection WinHLLAPI functions. Note that the "version" argument for WinHLLAPIStartup is a "short", and not a "ref".
[DllImport("WHLAPI32.DLL", ExactSpelling = true, CharSet = CharSet.Ansi)]
public static extern void WinHLLAPI(ref int functionNo, byte[] byteArray, ref int arraySize, ref int returnCode);
[DllImport("WHLAPI32.DLL", ExactSpelling = true, CharSet = CharSet.Ansi)]
public static extern int WinHLLAPIStartup(short version, byte[] byteArray);
[DllImport("WHLAPI32.DLL", ExactSpelling = true, CharSet = CharSet.Ansi)]
public static extern int WinHLLAPICleanup();
An incorrect declaration will result in a return value of WHLLVERNOTSUPPORTED (61444).
VB.Net declarations for WinHLLAPI:
Declare Function WinHLLAPI Lib "WHLAPI32.DLL" (ByRef Func As Integer, ByVal Buffer As Byte(), ByRef bSize As Integer, ByRef RetC As Integer) As Integer
Declare Function WinHLLAPIStartup Lib "WHLAPI32.DLL" (ByVal version As Short, ByVal Description As Byte()) As Integer
Declare Function WinHLLAPICleanup Lib "WHLAPI32.DLL" () As Integer
Additional Information
Original documentation for the WinHLLAPI specification,
published in the early 1990s by Microsoft and a consortium of terminal
emulation vendors, required that interactions between a custom
application and terminal emulation software using WinHLLAPI must begin
with a special function, "WinHLLAPIStartup". This function receives as
arguments a "version", and a pointer to a structure that will receive
certain (not very useful) information about the WinHLLAPI implementation. The
"version" argument must be 0x0101 (257).
Reflection requires WinHLLAPIStartup at the outset of WinHLLAPI interactions, otherwise subsequent WinHLLAPI calls will fail. This requirement is mandated in the WinHLLAPI specification. Micro Focus Extra! has never honored this requirement...Extra! does not require WinHLLAPIStartup at all. This means that a WinHLLAPI application originally written years ago for use with Extra! may fail to run correctly when used with Reflection if it does not call WinHLLAPIStartup before doing anything else.
WinHLLAPICsharpExample.zip - A console-based demo application illustrating WinHLLAPI within a simplified, reusable wrapper-class.