WinHLLAPI Extension Functions

This chapter describes the extension functions provided when using WinHLLAPI programming support.

Summary of WinHLLAPI Functions

The following WinHLLAPI functions are available for 3270, 5250, and VT:

WinHLLAPI Asynchronous Functions

The following sections describe the WinHLLAPI asynchronous functions.

WinHLLAPIAsync

This entry point is used for six WinHLLAPI functions that often take a long time to complete. With WinHLLAPIAsync, the function will be launched asynchronously and will not interfere with the continued progression of the calling application. These functions are: Wait (04), Start Host Notify (23), Start Close Intercept (41), Start Keystroke Intercept (50), Send File (90), and Receive File (91), and are described in WinHLLAPI Extension Functions.

HANDLE WinHLLAPIAsync (HWIND hWnd, LPWORD lpnFunction, LPBYTE lpData, LPWORD lpnLength, LPWORD lpnRetC)*

The parameter list is the same as WinHLLAPI except a window handle is required before the function number. Since the function operates asynchronously, its completion is signaled by a registered message. The window handle is required as the target of the message.

There are two messages that must be registered by the WinHLLAPI application through calls to RegisterWindowsMessage() with the strings WinHLLAPIAsync(for all functions except 90 and 91) and WinHLLAPIAsyncFileTransfer (for functions 90 and 91). The standard format is as follows:

WPARAM
contains the Task Handle returned by the original function call.
LPARAM
the high word contains the error code and the low word contains the original function number.

Wait (4)

This function determines whether the Host session is in an inhibited state. If, for some reason, the session is in an inhibited state, this function will signal your application with a message when either the inhibited state expires or your wait period has expired. The amount of time to wait is set with the Set Session Parameters (9) function.

Prerequisite Functions

Connect Presentation Space (1)

WinHLLAPIAsync(hWnd, lpwFunction, lpbyString, lpwLength, lpwReturnCode)

Call Parameters
Parameter Description
Data String NA
Data Length NA
PS Position NA
Return Codes
Code Description
WHLLOK The PS is uninhibited and ready for input.
WHLLNOTCONNECTED Your WinHLLAPI application is not connected to a valid host session.
WHLLPSBUSY Function timed out while still inhibited.
WHLLNHIBITED The PS is inhibited.
SHLLSYSERROR The function failed due to a system error.
WHLLCANCEL The asynchronous function was cancelled.
Remarks

Asynchronous Wait is used to notify the calling application when the inhibited state of the PS is expired. When inhibited state has expired, this version of Wait will post a WinHLLAPIAsync message to the window specified by the hWnd. The session options TWAIT, LWAIT, and NWAITaffect the length of time that this function will wait. See Set Session Parameters (9) for details on these session options.

Note:
If NWAIT is specified in the session parameters and the application registers using revision 1.1 of the WinHLLAPI implementation, the WINHLLAPIAsync call will work the same as the WinHLLAPI call and not send a message. If revision 1.0 is being used then Wait will return a message immediately with the inhibited status of the PS.

Start Host Notification (23)

This function enables you to notify your WinHLLAPI application of changes in the Host Session Presentation Space (PS) or Operation Information Area (OIA).

Prerequisite Functions

There are no prerequisite functions for this function.

WinHLLAPIAsync (hWnd, lpwFunction, lpbyString, lpwLength, lpwReturnCode)

Call Parameters
Parameter Description
Data String A 7-byte string in the following format:
Byte 1
Short name session ID of the desired Host session, or space or null for the current Host session.
Byte 2
Notification mode. "P" for presentation space update only, "O" for OIA update only, "B" for both presentation space and OIA updates. When calling WinHLLAPIAsync, this position can be "A".
Byte 3-6
Not used. Provided for compatibility with older applications.
Byte 7
Reserved or replaced with one of the following if using WinHLLAPIAsync and A in byte 2: P for presentation space update only, O for OIA update only; and B for both presentation space and OIA updates.
Data Length Length of Host event buffer (256 recommended).
PS Position NA
Return Parameters
Parameter Description
Data String Same as Data String on the call.
Return Codes
Code Description
WHLLOK Host notification enabled.
WHLLNOTCONNECTED The specified Host session is invalid.
WHLLPARAMETERERROR One of more parameters are invalid.
WHLLSYSERROR The function failed due to a system error.
WHLLCANCEL The asynchronous function was cancelled.
Remarks

Once enabled, Host notification is enabled until you call Stop Host Notification (25) or WinHLLAPICancelAsyncRequest(). The function initiates host notification and immediately returns control to your Windows HLLAPI application. This frees your application to perform other tasks while waiting for host updates. When an update occurs, the function will notify the window specified by hWnd with the registered message WinHLLAPIAsync.

Start Close Intercept (41)

This function intercepts user requests to close Z and I Emulator for Windows.

Prerequisite Functions

There are no prerequisite functions for this function.

WinHLLAPIAsync (hWnd, lpwFunction, lpbyString, lpwLength, lpwReturnCode)

Call Parameters
Parameter Description
Data String A 5-byte string for returned semaphore address. The first byte is the session short name of the session to query, or space or null for the current session.
Data Length Must be specified.
PS Position NA
Return Parameters
Parameter Description
Data String A 5-byte string with the following format:
Byte 1
Session short name, or space or null for the current session
Bytes 2-5
Semaphore address.
Return Code
Code Description
WHLLOK The function was successful.
WHLLNOTCONNECTED An invalid presentation space was specified.
WHLLPARAMETERERROR An invalid option was specified.
WHLLSYSERROR The function failed due to a system error.
WHLLCANCEL The asynchronous function was cancelled.
Remarks

Once enabled, Host notification remains enabled until you call Stop Close Intercept (43) or WinHLLAPICancelAsyncRequest (). Initially, the semaphore is set. After using this function, close requests from the user are discarded and the semaphore is cleared.

The function initiates close intercept and immediately returns control to your Windows HLLAPI application. This frees your application to perform other tasks while waiting for close requests. When a close request occurs, the function will notify the window specified by hWnd with the registered message WinHLLAPIAsync.

Start Keystroke Intercept (50)

This function intercepts keystrokes sent to a session by the user.

Prerequisite Functions

There are no prerequisite functions for this function.

WinHLLAPIAsync (hWnd, lpwFunction, lpbyString, lpwLength, lpwReturnCode)

Call Parameters
Parameter Description
Data String A 6-byte string in the following format:
Byte 1
Session short name, or space or null for the current Host session.
Byte 2
Keystroke intercept code. "D" causes only AID keystrokes to be intercepted; "L" causes all keystrokes to be intercepted.
Bytes 3-6
Reserved
Data Length Variable (256 is recommended)
PS Position NA
Return Code
Code Description
WHLLOK Keystroke intercept has been initiated.
WHLLNOTCONNECTED The Host session presentation space is invalid.
WHLLPARAMETERERROR One or more parameters are invalid.
WHLLPSBUSY Session is busy.
WHLLSYSERROR Function failed due to a system error.
WHLLCANCEL Asynchronous function was cancelled.
Remarks

The function initiates keystroke intercept and immediately returns control to your Windows HLLAPI application. This frees your application to perform other tasks while waiting for keystrokes. Once initiated, the function will post a WinHLLAPIAsync message to the window specified by hWnd whenever the user sends a key to the PS. After notification, the intercepted keystrokes can be handled in any way that is allowed by a normal EHLLAPI application. Take note that the keystroke buffer is of limited size so each keystroke should be handled and removed from the buffer.

Send File (90)

This function transfers a file from the PC to the Host.

Prerequisite Functions

There are no prerequisite functions for this function.

WinHLLAPIAsync (hWnd, lpwFunction, lpbyString, lpwLength, lpwReturnCode)

Call Parameters
Parameter Description
Data String SEND command parameters.
Data Length Length of Data String. NA if session option EOT is specified.
PS Position NA
Return Codes
Code Description
WHLLOK File transfer started successfully.
WHLLPARAMETERERROR Parameter error or Data Length is zero or greater than 255.
WHLLFTXCOMPLETE File transfer complete.
WHLLFTXSEGMENTED Transfer is complete with segmented records.
WHLLSYSERROR The function failed due to a system error.
WHLLTRANSABORTED File transfer aborted, either due to the user clicking the cancel button or because the timeout period has elapsed.
WHLLFILENOTFOUND PC file not found.
WHLLFTXCOMPLETECICS File transfer was successful (transfer to CICS).
WHLLACCESSDENIED Access denied to PC file.
WHLLMEMORY Insufficient memory.
WHLLINVALIDENVIRONMENT Invalid environment.
Remarks

Only one file transfer operation is supported per connected Host session.

The function initiates the file transfer and immediately returns control to your Windows HLLAPI application. This frees your application to perform other tasks while the file transfer is occurring. Once initiated the function will regularly post WinHLLAPIAsyncFileTransfer messages to the window specified by hWnd. These messages will notify the WinHLLAPI application of the status of the transfer and send a final message when the transfer is complete.

wParm
Is the status indicator: the high byte contains the Session ID, the low byte contains the status. If the low byte is zero, the file transfer is still in progress. If the low byte is one, the file transfer has completed.
lParm
If the low byte of wParm is zero (in progress), lParm is the number of bytes transferred. If the low byte wParm is one (completed), lParm is the completion code.

Receive File (91)

This function transfers a file from the PC to the Host.

Prerequisite Functions

There are no prerequisite functions for this function.

WinHLLAPIAsync (hWnd, lpwFunction, lpbyString, lpwLength, lpwReturnCode)

Call Parameters
Parameter Description
Data String RECEIVE command parameters.
Data Length Length of Data String. NA if session option EOT is specified.
PS Position NA
Return Codes
Code Description
WHLLOK File transfer started successfully.
WHLLPARAMETERERROR Parameter error or Data Length is zero or greater than 255.
WHLLFTXCOMPLETE File transfer complete.
WHLLFTXSEGMENTED Transfer is complete with segmented records.
WHLLSYSERROR The function failed due to a system error.
WHLLTRANSABORTED File transfer aborted, either due to the user clicking the cancel button or because the timeout period has elapsed.
WHLLFILENOTFOUND PC file not found.
WHLLFTXCOMPLETECICS File transfer was successful (transfer to CICS).
WHLLACCESSDENIED Access denied to PC file.
WHLLMEMORY Insufficient memory.
WHLLINVALIDENVIRONMENT Invalid environment.
Remarks

Only one file transfer operation is supported per connected Host session.

The function initiates the file transfer and immediately returns control to your Windows HLLAPI application. This frees your application to perform other tasks while the file transfer is occurring. Once initiated the function will regularly post WinHLLAPIAsyncFileTransfer messages to the window specified by hWnd. These messages will notify the WinHLLAPI application of the status of the transfer and send a final message when the transfer is complete.

wParm
Is the status indicator: the high byte contains the Session ID, the low byte contains the status. If the low byte is zero, the file transfer is still in progress. If the low byte is one, the file transfer has completed.
lParm
If the low byte of wParm is zero (in progress), lParm is the number of bytes transferred. If the low byte wParm is one (completed), lParm is the completion code.

WinHLLAPICancelAsyncRequest

This function cancels an outstanding asynchronous function launched by a call to WinHLLAPIAsync().

Syntax

int WinHLLAPICancelAsyncRequest (HANDLE hAsyncTask, WORD wFunction)

Parameters

hAsyncTask
The handle returned by WinHLLAPIAsync() when the function was initiated.
wFunction
The function number of the asynchronous task to cancel. Because this parameter is required for revision 1.1 but not in 1.0, it is optional.

With this function, any asynchronous task previously initiated by a call to WinHLLAPIAsync() may be canceled while still outstanding.

Returns

The return value indicates if the specified function was, in fact, canceled. If the function was canceled then the return value is WHLLOK (0). If the outstanding asynchronous function was not cancelled, one of the following codes will be returned.

WHLLINVALID
hAsyncTask is not a valid task handle.
WHLLALREADY
The asynchronous task specified by hAsyncTask has already completed.

Initialization and Termination Functions

The following section describes the initialization and termination functions of WinHLLAPI programming support.

WinHLLAPI Startup

This function is used to register the application with the WinHLLAPI implementation and should be called before any other call to the WinHLLAPI implementation. This implementation supports Versions 1.0 and 1.1 of the WinHLLAPI specification. The WinHLLAPI application should negotiate version compatibility with this function.

Syntax

int WinHLLAPIStartup(WORD wVersionRequired, LPWHLLAPIDATA lpData)

Parameters

wVersionRequired
This is the version required by the WinHLLAPI application. The low byte contains the major version number and the high byte contains the minor version (or revision) number.
lpData
This is a pointer to a WHLLAPIDATA structure which will receive the implementations version number and a string describing the WinHLLAPI implementation provider. The WHLLAPIDATA structure is defined as:
#define  WHLLDESCRIPTION_LEN   127
typedef  struct  tagWHLLAPIDATA
{
     WORD  wVersion;
     Char  szDescription[WHLLDESCRIPTION_LEN + 1];
}WHLLAPIDATA,  *  PWHLLAPIDATA,  FAR  *LPWHLLAPIDATA;

Returns

The return value indicates success or failure of registering the WinHLLAPI application with the implementation. If registration was successful, the return value is WHLLOK (zero). Otherwise, it is one of the following:

WHLLSYSNOTREADY
Indicates that the underlying network subsystem is unavailable.
WHLLVERNOTSUPPORTED
Indicates that the version requested is not provided by this implementation. This implementation supports Versions 1.0 and 1.1 only.

WinHLLAPI Cleanup

The WinHLLAPI specification recommends that this function be used by the WinHLLAPI application to de-register from the WinHLLAPI implementation.

Syntax

BOOL WinHLLAPICleanup()

Returns

Returns TRUE if the unregistration was successful. Otherwise, it returns FALSE.

Blocking Routines

The following sections describe the blocking routines supported by WinHLLAPI programming.

Note:
Although blocking routines are supported for WinHLLAPI compliance, use of them is not recommended. Use of the WinHLLAPIAsync functions are the recommended method for asynchronous processing.

WinHLLAPIIsBlocking

This function tells the calling WinHLLAPI application thread whether it is in the process of executing a blocking call. A blocking call is any synchronous function that takes a long time to execute and does not return until complete. There are five blocking calls in this implementation of WinHLLAPI. The blocking calls are: Get Key (51), Wait (4), Pause (18), Send File (90), and Receive File (91).

Syntax

BOOL WinHLLAPIIsBlocking()

Returns

If the WinHLLAPI application thread is in the middle of a blocking call, the function returns TRUE, otherwise, it returns FALSE.

Remarks

Because the default blocking-hook allows messages to be processed during blocking calls, it is possible to call the blocking call again.

WinHLLAPISetBlockingHook

This function sets an application-defined procedure to be executed while waiting for the completion of a blocking call. A blocking call is any synchronous function that takes a long time to execute and does not return until complete. There are five blocking calls in this implementation of WinHLLAPI. The blocking calls are: Get Key (51), Wait (4), Pause (18), Send File (90), and Receive File (91).

Syntax

FARPROC WinHLLAPISetBlockingHook(FARPROC lpfnBlockingHook)

Parameters

lpfnBlockingHook
This is a pointer to the new blocking procedure.

Description

The WinHLLAPI implementation has a default blocking procedure that consists of nothing more than a message handler. This default mechanism is shown in the following example:

BOOL    DefaultBlockingHook
{
      MSG msg;
 
      if (PeekMessage (&msg, NULL, 0, 0, xfPM_NOREMOVE))
      {
            if(msg.message = = WM_QUIT)
            {
                return FALSE;
            }
            PeekMessage (&msg, NULL, 0, 0, PM_REMOVE);
            TranslateMessage (&msg);
            DispatchMessage (&msg);
      }
return TRUE;
}

The blocking hook is implemented on a per-thread basis. A blocking hook set by this function will stay in effect for the thread until it is replaced by another call to WinHLLAPISetBlockingHook() or until the default is restored by a call to WinHLLAPIUnhookBlockingHook().

The Blocking function must return FALSE if it receives a WM_QUIT message so WinHLLAPI can return control to the application to process the message and terminate gracefully. Otherwise, the function should return TRUE.

Returns

This function returns a pointer to the blocking function being replaced.

WinHLLAPIUnhookBlockingHook

This function restores the default blocking-hook for the calling thread.

Syntax

BOOL WinHLLAPIUnhookBlockingHook()

Returns

This function returns TRUE if the default blocking mechanism was successfully restored, otherwise it returns FALSE.

WinHLLAPICancelBlockingCall

This function cancels an executing blocking call in the current thread. A blocking call is any synchronous function that takes a long time to execute and does not return until complete. There are five blocking calls in this implementation of WinHLLAPI. The blocking calls are Get Key (51), Wait (4), Pause (18), Send File (90), and Receive File (91). If one of these is blocking calls are cancelled, the cancelled function will return WHLLCANCEL.

Syntax

int WinHLLAPICancelBlockingCall()

Returns

The return value indicates if the specified function was, in fact, canceled. If the function was canceled, then the return value is WHLLOK (0). If there are no outstanding blocking functions, then the following return code will be returned:

WHLLINVALID
Indicates that there is no blocking call currently executing.