GetAppcConfig

The GetAppcConfig function provides an asynchronous entry point for retrieving the remote systems to which a particular local LU can connect.

HANDLE WINAPI GetAppcConfig(
HANDLE hWnd,
LPSTR pLocalLu,
LPSTR pMode,
LPINT pNumRemLu,
INT iMaxRemLu,
PSTR pRemLu,
LPINT pAsyncRetCode
);

Parameters

hWnd

Supplied parameter. Contains the handle of the window that is to receive an asynchronous completion message when the call has completed. If non-null, the completion message will be posted to this window handle. In this case, pAsyncRetCode (the last parameter) must be null. Asynchronous message completion is the recommended approach for a Windows applications to use this function.

pLocalLu

Supplied parameter. Specifies the address of a buffer containing the local LU name for which information is returned. This local LU name must be specified as follows:

• Nonpadded
• Null-terminated
• ASCII string
• Maximum length of eight bytes (excluding the terminator)

To request that the user's default local LU be used, the buffer should contain eight spaces followed by a null.

pMode

Supplied parameter. Specifies the address of a buffer containing the mode name for which information is returned. In Microsoft® SNA Server version 3.0 and later this parameter is not used, but for compatibility with earlier versions of SNA Server a mode name must be specified as follows:

• Nonpadded
• Null-terminated
• ASCII string
• Maximum length of eight bytes (excluding the terminator)

pNumRemLu

Supplied parameter. Specifies the address of an integer variable that when the function completes will contain the number of remote LUs that would have been returned, had the buffer specified by pRemLu been large enough to accommodate all of the remote LUs.

iMaxRemLu

Supplied parameter. Specifies the number of remote LU names that can be held by the buffer indicated by pRemLu.

pRemLu

Supplied parameter. Specifies the address of the buffer that will hold the remote LU names after the function completes. The information will be returned as an array of strings. Each remote LU name will be stored in the buffer as follows:

• Nonpadded
• Null-terminated
• ASCII string
• Maximum length of eight bytes (excluding the terminator)

The strings start every nine bytes in the buffer, and thus (pRemLu + (i–1)*9) gives the start of the ith string. In the case where the buffer is too small to hold all the names, only iMaxRemLu strings will be returned.

pAsyncRetCode

Supplied parameter. Specifies the address of an integer variable used to store the return code from this function, if the supplied address is non-null. The return codes will be the same as those returned by an asynchronous completion message. While the call is completing, the value of the this variable will be APPC_CFG_PENDING. When this asynchronous call is completed, the value of this variable will contain some return code other than APPC_CFG_PENDING.

This variable is used by polling for completion when asynchronous message completion to a window handle is not used.

Note that if pAsyncRetCode is used, hWnd must be null.

Return Values

The meaning of the immediate return value depends on whether or not the asynchronous request was accepted. To test for acceptance, evaluate the expression:

(<Returned Handle> & APPC_CFG_SUCCESS)

If the expression is FALSE, the request was rejected. The return value is then one of the synchronous return codes in the following list. If the expression is TRUE, the request was accepted, and one of the following cases will apply.

• If hWnd was non-null, a completion message will arrive in the following form:

• If pAsyncRetCode was non-null, then the specified integer variable will be set to APPC_CFG_PENDING. After this function completes asynchronously, its value will change to one of the asynchronous return codes listed below.

Synchronous Return Codes

appc_cfg_error_no_appc_init

The Windows APPC library needs to be initialized by a call to WinAPPCStartup before calling GetAPPCConfig and this has not been done.

appc_cfg_error_invalid_hwnd

The handle passed in hWnd was non-null, yet not a valid window handle.

appc_cfg_error_bad_pointer

The hWnd parameter was null, indicating that completion was signaled by setting the integer variable pointed to by pAsyncRetCode, but pAsyncRetCode was not a valid pointer.

appc_cfg_error_unclear_completion_mode

Both hWnd and pAsyncCompletion were non-null, so GetAPPCConfig was unable to decide how completion should be signaled.

appc_cfg_error_too_many_requests

Too many GetAPPCConfig calls are already being processed (currently, this indicates 16 requests are outstanding). Try the call again after a delay. For the Microsoft® Windows® version 3.x system, you must yield during this period.

appc_cfg_error_general_failure

An unexpected error occurred, probably of a system nature.

Asynchronous Return Codes

appc_cfg_success_no_default_remote

The configuration information has been retrieved, and either no default remote LU was defined or it was not accessible by the specified local LU.

appc_cfg_success_default_remote

The configuration information has been retrieved, and there is a default remote LU that is accessible by the specified local LU.

appc_cfg_error_no_default_local_lu

An attempt was made to retrieve remote LUs partnered with the default local LU, but no default local LU was configured.

appc_cfg_error_bad_local_lu

The local LU specified is either not configured, or is not valid for the calling verb.

appc_cfg_error_general_failure

An unexpected error occurred, probably of a system nature.

Remarks

WinAPPCStartup must be called before using GetAPPCConfig.

Whether an error code represents success or failure can be determined by evaluating either (RetCode& APPC_CFG_SUCCESS) to test for success or (RetCode& APPC_CFG_FAILURE) to test for failure.

The following code fragment shows how a console application can test completion:

while (*pAsyncRetCode == APPC_CFG_PENDING)
{
    sleep(250);
}