HLLAPI trace log message: WinHllapi version negotiation failed.

  • Document ID:7023496
  • Creation Date:05-Nov-2018
  • Modified Date:09-Nov-2018
    • Micro Focus Products:
      Reflection Desktop

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)

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.