|
|
|
|
A Windows application accesses APPC using the following entry points:
Registers the application as a Windows APPC user, and determines whether the APPC software supports the level of function required by the application.
Issues an APPC verb. The verb normally completes asynchronously and does not block; APPC indicates the completion by posting a message to the application window.
Issues an APPC verb. If the verb completes asynchronously, APPC indicates the completion by signaling an event handle. Use this function instead of the blocking versions of the verbs to allow multiple sessions to be handled on the same thread.
Cancels an outstanding asynchronous verb (one issued using the WinAsyncAPPC entry point). Depending on which verb is outstanding, this may also end the conversation or the TP or deactivate the session being used by a conversation.
Unregisters the application when it has finished using APPC.
Issues an APPC verb. The verb blocks; that is, the application's processing is suspended until APPC has finished processing the verb and returned the results.
Cancels an outstanding blocking verb (one issued using the APPC entry point). Depending on which verb is outstanding, this may also end the conversation or the TP, or deactivate the session being used by a conversation. For more information about the circumstances in which this call may be required, see Blocking Verbs.
Checks whether there is a blocking verb outstanding for this application. For more information about the circumstances in which this call may be required, see Blocking Verbs.
Specifies the blocking procedure that APPC uses while processing blocking verbs; this replaces APPC's default blocking procedure. The blocking procedure is called repeatedly until the verb processing has completed. For more information, see Blocking Verbs.
Unregisters the blocking procedure specified by a previous WinAPPCSetBlockingHook call, so that APPC reverts to using the default blocking procedure.
Returns information about remote LUs configured for use by a specified local LU and mode. This function is provided for use by 5250 emulation programs; the information returned is taken from the 5250 user records in the SNAP-IX configuration.
Generates a printable character string for the primary and secondary return codes obtained on an APPC verb.
These entry points are defined in the Windows APPC header file winappc.h. This file is installed in the subdirectory /sdk within the directory where you installed the Windows Client software.
The application must call WinAPPCStartup before attempting to issue any APPC verbs.
It then issues APPC verbs using one of the following entry points:
WinAsyncAPPC or WinAsyncAPPCEx (asynchronous). If you are developing new applications for Windows, use one of these entry points.
APPC (blocking). This entry point is provided for compatibility with the Solaris APPC implementation. Blocking Verbs provides more information about how blocking verbs operate in the Windows environment.
An application that provides 5250 emulation can use GetAppcConfig to obtain information about remote APPC LUs that can be accessed using a given local LU.
If a verb returns with return codes other than AP_OK, the application can use GetAppcReturnCode to obtain a text string representation of these return codes, which can be used to generate standard error messages.
When the application has finished issuing APPC verbs, it must call WinAPPCCleanup before terminating. After calling WinAPPCCleanup , the application must not attempt to issue any more APPC verbs (unless it first calls WinAPPCStartup to reinitialize).
The following sections describe these Windows entry points.
The application uses WinAPPCStartup to register as a Windows APPC user and to determine whether the APPC software supports the Windows APPC version that the application requires.
int WINAPI LOADDS WinAPPCStartup (
WORD wVersionRequired;
WAPPCDATA far * lpData;
)
typedef struct
{
WORD wVersion;
char szDescription[128];
} WAPPCDATA;
When the application uses the WinAPPCStartup entry point to issue a verb, it supplies the following parameters:
The version of Windows APPC that the application requires. The low-order byte specifies the major version number, and the high-order byte specifies the minor version number. For example:
| Version | wVersionRequired |
| 1.0 | 0x0001 |
| 1.1 | 0x0101 |
| 2.0 | 0x0002 |
If the application can use more than one version, it specifies the highest version that it can use.
WinAPPCStartup returns one of the following values:
The application was registered successfully and the Windows APPC software
supports either the version number specified by the application or a lower
version. The application should check the version number in the
The version number specified by the application was lower than the lowest version supported by the Windows APPC software. The application was not registered.
The application was not registered. This may be because the SNAP-IX software has not been started, or the local node is not active, or because of another system failure such as a resource shortage.
If the return value from WinAPPCStartup is
0 (zero), the
The Windows APPC version number that the software supports, in the same format as the wVersionRequired parameter. If the software supports the requested version number, this parameter is set to the same value as the wVersionRequired parameter; otherwise it is set to the highest version that the software supports, which is lower than the version number supplied by the application. The application must check the returned value and take action as follows:
If the returned version number is the same as the requested version number, the application can use this Windows APPC implementation.
If the returned version number is lower than the requested version number, the application can use this Windows APPC implementation but must not attempt to use features that are not supported by the returned version number. If it cannot do this because it requires features not available in the lower version, it should fail its initialization and not attempt to issue any APPC verbs.
A text string describing the Windows APPC software.
The application uses this function to issue an APPC verb. If the verb completes asynchronously, APPC indicates the completion by posting a message to the application's Windows handle.
Before using the WinAsyncAPPC call for the first time, the application must use the RegisterWindowMessage call to obtain the message identifier that APPC will use for messages indicating asynchronous verb completion. For more information, see Usage.
HANDLE WINAPI LOADDS WinAsyncAPPC (
HWND hWnd,
long vcbptr
);
The supplied parameters are:
A Windows handle that APPC will use to post a message indicating asynchronous verb completion.
A pointer to the VCB structure for the verb. This parameter is defined as a long integer, and so needs to be cast from a pointer to a long integer. For more information about the VCB structure and on its usage for individual verbs, see APPC Control Verbs and APPC Conversation Verbs.
The APPC VCBs contain many parameters marked as reserved
;
some of these are used internally by the SNAP-IX software, and others are
not used in this version but may be used in future versions. Your application
must not attempt to access any of these reserved parameters; instead, it must
set the entire contents of the VCB to zero to ensure that all of these parameters
are zero, before it sets other parameters that are used by the verb. This
ensures that SNAP-IX will not misinterpret any of its internally-used parameters,
and also that your application will continue to work with future SNAP-IX
versions in which these parameters may be used to provide new functions.
To set the VCB contents to zero, use memset:
memset(vcb, 0, sizeof(vcb));
The return value from the function is one of the following:
The function call was successful (accepted). When the verb later completes, APPC uses this handle as an identifier in the message passed to the application's window procedure (for more information, see Usage). The application also uses this handle as a parameter to the WinAPPCCancelAsyncRequest call if it needs to cancel the outstanding verb.
The function call was not successful (not accepted).
Before using WinAsyncAPPC for the first time, the application must use the RegisterWindowMessage call to obtain the message identifier that APPC will use for messages indicating asynchronous verb completion. RegisterWindowMessage is a standard Windows function call, not specific to APPC; refer to your Windows documentation for more information about the function. (You do not need to issue the call again before subsequent APPC verbs; the returned value will be the same for all calls issued by the application.)
The application must pass the string WinAsyncAPPC
to
the function; the returned value is a message identifier.
Each time an APPC verb that was issued using the WinAsyncAPPC entry point completes asynchronously, APPC posts a message to the Windows handle specified on the WinAsyncAPPC call. The format of the message is as follows:
The message identifier is the value returned from the RegisterWindowMessage call.
The lParam argument contains the address of the VCB that was supplied to the original WinAsyncAPPC call; the application can use this address to access the returned parameters in the VCB structure.
The wParam argument contains the handle that was returned to the original WinAsyncAPPC call.
The application uses this function to issue an APPC verb. If the verb completes asynchronously, APPC indicates the completion by signaling an event handle. Use this function instead of the blocking versions of the verbs to allow multiple sessions to be handled on the same thread.
HANDLE WINAPI WinAsyncAPPCEx (
HANDLE eventhandle,
long vcbptr
);
The supplied parameters are:
An event handle that APPC will signal to indicate asynchronous verb completion.
A pointer to the VCB structure for the verb. This parameter is defined as a long integer, and so needs to be cast from a pointer to a long integer. For more information about the VCB structure and on its usage for individual verbs, see APPC Control Verbs and APPC Conversation Verbs.
The APPC VCBs contain many parameters marked as reserved
;
some of these are used internally by the SNAP-IX software, and others are
not used in this version but may be used in future versions. Your application
must not attempt to access any of these reserved parameters; instead, it must
set the entire contents of the VCB to zero to ensure that all of these parameters
are zero, before it sets other parameters that are used by the verb. This
ensures that SNAP-IX will not misinterpret any of its internally-used parameters,
and also that your application will continue to work with future SNAP-IX
versions in which these parameters may be used to provide new functions.
To set the VCB contents to zero, use memset:
memset(vcb, 0, sizeof(vcb));
The return value from the function is one of the following:
The function call was successful (accepted) and the return value is an asynchronous task handle. When the verb later completes, APPC uses this handle for event notification to the application (for more information, see Usage). The application also uses this handle as a parameter to the WinAPPCCancelAsyncRequest call if it needs to cancel the outstanding verb.
The function call was not successful (not accepted).
This function is intended for use with WaitForSingleObject or WaitForMultipleObjects in the Win32 API. When the asynchronous operation is complete, the application is notified through the signaling of the event. Upon signaling of the event, examine the primary return code and secondary return code for any error conditions.
The application uses this function to cancel an oustanding APPC verb (issued using the WinAsyncAPPC entry point).
int WINAPI LOADDS WinAPPCCancelAsyncRequest (HANDLE Handle);
The supplied parameter is:
The handle that was returned on the original WinAsyncAPPC call for the verb.
The return value from the function is one of the following:
The outstanding verb was canceled successfully.
The supplied parameter did not match the handle of any outstanding APPC verb.
The APPC verb identified by the supplied handle has already completed. (The application may already have processed the message resulting from the verb completion, or the message may still be waiting in the application's message queue.)
In addition to canceling the outstanding verb, APPC may also end the conversation or TP on which the verb was issued, bring down the session, or both. The action taken depends on the verb that was canceled. APPC also posts a message to the application indicating completion of the canceled verb; the primary return code for the verb is AP_CANCELLED.
The application uses the WinAPPCCleanup function to unregister as a Windows APPC user, after it has finished issuing APPC verbs.
BOOL WINAPI LOADDS WinAPPCCleanup (void);
No parameters are supplied with the WinAPPCCleanup function.
The return value from the function is one of the following:
The application was unregistered successfully.
An error occurred during processing of the call, and the application was not unregistered. Check the log files for messages indicating the cause of the failure.
This section describes how blocking verbs operate in the Win32 environment if the calling application is single-threaded, and provides information that you need to be aware of when writing applications to use blocking verbs. (Typically a Win32 application would use multiple threads to avoid the problem of a blocking verb blocking the entire application.)
Although a verb issued to the APPC entry point appears to suspend the application until verb processing is completed, the APPC library has to yield control of the system while waiting for SNAP-IX to complete the processing, in order to allow other processes to run. To do this, the application uses a blocking function, which is called repeatedly while the library is waiting; the function enables Windows messages to be sent to other processes. For more information about this function, see Default Blocking Function.
It is possible for the blocking function to dispatch a message to the application that issued the original blocking verb; in this case, the application can be re-entered even though it has a blocking call outstanding. In these circumstances, the application can continue with other processing not related to issuing APPC verbs. However, it cannot issue another verb to the APPC entry point (or to any other SNAP-IX API) while the first verb is outstanding; the verb will be rejected with the primary return code AP_THREAD_BLOCKING.
The application can check whether a blocking verb is outstanding (that is, whether it has been re-entered as a result of a received message while the verb was outstanding) by using the WinAPPCIsBlocking function (for more information, see WinAPPCIsBlocking). If this function indicates that a blocking call is outstanding, the application should not attempt to issue further APPC verbs using the blocking entry point. The application can, however, do the following:
Continue with other processing.
Issue APPC verbs using the asynchronous entry point.
Issue WinAPPCCancelBlockingCall to cancel the outstanding blocking verb.
The standard blocking function used by the Windows APPC library is as follows:
BOOL far pascal DefaultBlockingHook (void) {
MSG msg;
/* get the next message if any */
if ( PeekMessage (&msg,NULL,0,0,PM_NOREMOVE) ) {
if ( msg.message = = WM_QUIT )
return FALSE; // let app process WM_QUIT
PeekMessage (&msg,NULL,0,0,PM_REMOVE);
TranslateMessage (&msg);
DispatchMessage (&msg);
}
/* TRUE if no WM_QUIT received */
return TRUE;
}
If the application needs to have other processing performed as part of the blocking function, it can specify its own blocking function to replace the default one provided by APPC. To do this, it uses the WinAPPCSetBlockingHook call (see WinAPPCSetBlockingHook).
A blocking function must return FALSE if it receives a WM_QUIT message; this means that Windows APPC returns control to the application, which can then process the message and terminate. Otherwise, the function must return TRUE.
The application uses this function to issue an APPC verb, which blocks until verb processing is completed. For compatibility with earlier APPC implementations, SNAP-IX also provides the entry points APPC_C and APPC_P, which can be used in the same way as APPC.
This entry point provides support for synchronous APPC verbs on Windows, which may assist in migrating from other operating system environments.
void WINAPI LOADDS APPC (
long vcbptr
)
The supplied parameter is:
A pointer to the VCB structure for the verb. This parameter is defined as a long integer, and so needs to be cast from a pointer to a long integer. For the definition of the VCB structure for each APPC verb, see APPC Control Verbs and APPC Conversation Verbs.
The APPC VCBs contain many parameters marked as reserved
;
some of these are used internally by the SNAP-IX software, and others are
not used in this version but may be used in future versions. Your application
must not attempt to access any of these reserved parameters; instead, it must
set the entire contents of the VCB to zero to ensure that all of these parameters
are zero, before it sets other parameters that are used by the verb. This
ensures that SNAP-IX will not misinterpret any of its internally-used parameters,
and also that your application will continue to work with future SNAP-IX
versions in which these parameters may be used to provide new functions.
To set the VCB contents to zero, use memset:
memset(vcb, 0, sizeof(vcb));
The function does not return a value. When the call returns, the application should check the primary_rc and secondary_rc parameters in the VCB structure to determine whether the verb completed successfully. For information about the parameters returned in the VCB structure, see the descriptions of individual verbs in APPC Control Verbs and APPC Conversation Verbs.
The application uses the WinAPPCCancelBlockingCall function to cancel an outstanding blocking APPC verb (issued using the APPC entry point).
BOOL WINAPI LOADDS WinAPPCCancelBlockingCall (void);
No parameters are supplied for this entry point. (There can be only one blocking verb outstanding at any time, so there is no need to identify the particular verb to be canceled.)
The return value from the function is one of the following:
The outstanding verb was canceled successfully.
Either no blocking APPC verb was outstanding, or an error occurred during processing of the call and the verb was not canceled.
In addition to canceling the outstanding verb, APPC also ends the conversation on which the verb was issued and brings down the session. If the verb is one that relates to a TP rather than to a conversation (such as RECEIVE_ALLOCATE or TP_STARTED), APPC ends the TP.
The application uses the WinAPPCIsBlocking function to check whether there is a blocking APPC verb outstanding (a verb issued using the APPC entry point).
BOOL WINAPI LOADDS WinAPPCIsBlocking (void);
No parameters are supplied with this function.
The return value from the function is one of the following:
A blocking APPC verb is outstanding. If necessary, the application can use the WinAPPCCancelBlockingCall function to cancel it.
A blocking APPC verb is not outstanding.
The application uses this call to specify its own blocking function, which APPC will use instead of the default blocking function. For more information about how the blocking function operates and on the functions it must perform, see Blocking Verbs.
FARPROC WINAPI LOADDS WinAPPCSetBlockingHook (FARPROC lpBlockFunc);
The supplied parameter is:
The procedure instance address of the application's blocking function. The application should use the MakeProcInstance call to obtain this address; refer to your Windows documentation for more information.
The return value is the procedure instance address of the previous blocking function. If the application is using more than one blocking function, and will need to restore the previous blocking function later, it should save this address; it can then issue WinAPPCSetBlockingHook again using the saved value, to restore the previous blocking function. If it is using only one blocking function, or will not need to restore the previous value, it can ignore the return value from this call.
The new blocking function remains in effect until the application issues one of the following calls:
WinAPPCSetBlockingHook (with a different procedure instance address) to specify a new blocking function or to restore a previous one
WinAPPCUnhookBlockingHook (see WinAPPCUnhookBlockingHook), to stop using the current blocking function and return to the default blocking function
The application uses this call to remove its own blocking function, which it has previously specified using WinAPPCSetBlockingHook, and revert to using APPC's default blocking function.
BOOL WINAPI LOADDS WinAPPCUnhookBlockingHook (void);
No parameters are supplied for this function.
The return value from the function is one of the following:
The blocking function was removed successfully; any further blocking calls will use the default blocking function.
The call did not complete successfully.
The GetAppcConfig function is provided for use by 5250 emulation programs. The function returns information about the remote LUs that a specified local LU can access, as defined in the 5250 emulation user records in the SNAP-IX configuration.
To determine the information required by this call, SNAP-IX checks the user name configured for the Windows client against the 5250 user records defined in the configuration (or, if the user name is not explicitly defined, checks for a <DEFAULT> record). In the appropriate user record, it matches the local LU alias and mode name supplied on this call against the session definitions, and returns the remote LU alias for each matching session.
The application supplies a Windows handle to which APPC can post a message when the verb completes asynchronously. Before using GetAppcConfig for the first time, the application must use RegisterWindowMessage to obtain the message identifier that APPC will use for the message indicating asynchronous completion of the call, and WinAPPCStartup to register as a Windows APPC application. For more information, see the description of WinAPPCStartup in WinAPPCStartup and Usage.
An alternative method of indicating completion of the call is to supply a pointer to an integer value (the AsyncRetCode parameter) in which APPC can return values to indicate that the call has failed, is in progress, or has completed. Windows applications are recommended to use the first method, supplying a Windows handle.
HANDLE WINAPI LOADDS GetAppcConfig (
HWND hWnd,
char far *LocalLU,
char far *Mode,
int far *NumRemLU,
int MaxRemLU,
char far *RemLU,
int far *AsyncRetCode
);
The supplied parameters are:
A Windows handle that APPC will use to post a message indicating asynchronous completion of this call. If this parameter is used, the pointer to the AsyncRetCode parameter must be a null pointer.
A pointer to the alias of the local LU for which configuration information is required. This is an ASCII string of up to eight characters, terminated with a null character (binary zero); if the LU alias is shorter than eight characters, it must be followed immediately by the null character and not space-padded.
To indicate the default local LU, set this parameter to point to a string consisting of eight ASCII spaces followed by a null character.
A pointer to the name of the mode (used by the local LU) for which configuration information is required. This is an ASCII string of up to eight characters, terminated with a null character (binary zero); if the mode name is shorter than eight characters, it must be followed immediately by the null character and not space-padded. For 5250 emulation programs, the mode name is normally QPCSUPP.
A pointer to an integer that APPC can use to return the number of remote LUs configured.
The maximum number of remote LU aliases that can be accommodated in the supplied data buffer (see the following parameter). Each LU alias requires 9 bytes, so the length of the supplied buffer must be at least nine times the supplied value of MaxRemLU.
A buffer to contain the returned remote LU aliases.
If the application is using the recommended method of indicating completion, this parameter is reserved; the application must supply a null pointer.
If the application is using the alternative method, this parameter is a pointer to the integer that APPC uses for the asynchronous return code from the function. In this case, the hWnd parameter must be a null handle.
When the call returns, the application can test the value of the expression
ReturnedHandle & APPC_CFG_SUCCESS
to determine
whether the function was successful.
If the value of the expression ReturnedHandle
& APPC_CFG_SUCCESS
is TRUE, and the
application is using the recommended method to indicate completion, the return
value is a handle. When the function later completes, APPC uses this handle
as an identifier in the message passed to the application's window procedure
(for more information, see Usage).
If the value of the expression ReturnedHandle
& APPC_CFG_SUCCESS
is TRUE, and the
application is using the alternative method to indicate completion, the
AsyncRetCode parameter is set to APPC_CFG_PENDING
. The application should test this value periodically to check
for completion. When the function later completes, APPC sets this parameter
to one of the asynchronous return codes listed in Usage.
If the value of the expression is FALSE, the function call was not accepted. The value of ReturnedHandle is one of the following:
The application has not issued the WinAPPCStartup call. This call must be issued before GetAppcConfig is used.
The application supplied a Windows handle that was not valid.
The application supplied a null pointer to a Windows handle, to use the alternative method for indicating completion, but supplied a pointer for the AsyncRetCode parameter that was not valid.
The application supplied both a Windows handle (in the hWnd parameter) and a non-null pointer to the AsyncRetCode parameter, so APPC could not determine how to indicate asynchronous completion.
Too many GetAppcConfig requests are already outstanding. The application should yield, to allow other processes to run, and retry the call later.
A system error occurred.
Before using GetAppcConfig for the first time, the application must use the RegisterWindowMessage call to obtain the message identifier that APPC will use for messages indicating asynchronous completion. RegisterWindowMessage is a standard Windows function call, not specific to APPC; refer to your Windows documentation for more information about the function. (The application does not need to issue the call again before subsequent GetAppcConfig calls; the returned value will be the same for all calls issued by the application.)
The application must pass the value WIN_APPC_CFG_COMPLETION_MSG to the function; the returned value is a message identifier.
An application can indicate completion by using a Windows handle or by using an alternative method, as follows:
If the application is using a Windows handle to indicate completion, APPC posts a message to this Windows handle when the call completes asynchronously. The format of the message is as follows:
The message identifier is the value returned from the RegisterWindowMessage call.
The wParam argument contains the handle that was returned to the original GetAppcConfig call.
The lParam argument contains one of the following asynchronous return codes:
The configuration was retrieved successfully. No default remote LU is configured for the specified local LU and mode.
The configuration was retrieved successfully. A default remote LU is configured for the specified local LU and mode. (SNAP-IX does not return this value, because it does not have a concept of configuring default remote LUs; however, the application should allow for this return code to ensure compatibility with other APPC implementations.)
The application supplied a blank local LU alias, indicating the default local LU, but no default local LU is configured.
The supplied local LU alias did not match any configured local LU alias used for 5250 emulation.
A system error occurred.
If the application is using the alternative method to indicate completion, APPC sets the asynchronous return code to one of the return codes in the list for the lParam argument (in the Windows message) when the call completes.
The application can test for success or failure by testing the expressions
RetCode & APPC_CFG_SUCCESS
or
RetCode & APPC_CFG_FAILURE
, where
RetCode is the lParam argument in
the Windows message or the AsyncRetCode parameter returned
to the application. If RetCode & APPC_CFG_SUCCESS
is TRUE, the call was successful; if
RetCode & APPC_CFG_FAILURE
is TRUE
, the call failed.
If the call was successful, the application can then check the values of the NumRemLU and RemLU parameters:
NumRemLU contains the total number of remote LUs configured. If this number is greater than the supplied MaxRemLU parameter, the supplied buffer was not large enough to contain all the remote LU aliases. The application can use the returned aliases, or can reissue GetAppcConfig with a large enough buffer to contain all the aliases.
RemLU contains the aliases of the remote LUs. Each alias is a string of up to eight characters followed by a null character, and occupies 9 bytes of the buffer. The number of LU aliases returned is the smaller of the supplied parameter MaxRemLU and the returned parameter NumRemLU.
To determine the information required by this call, SNAP-IX checks the user name configured for the Windows client against the 5250 user records defined in the configuration (or, if the user name is not explicitly defined, checks for a <DEFAULT> record). In the appropriate user record, it matches the local LU alias and mode name supplied on this call against the session definitions, and returns the remote LU alias for each matching session.
This call returns a printable character string interpreting the return codes from a supplied VCB. The string can be used to generate application error messages for return codes other than AP_OK.
This call provides strings for display to the end user of an APPC application. For return codes indicating configuration problems or user errors (for example if a required component is not configured or not started), the string should provide sufficient information to help the user correct the problem. For return codes indicating application errors (for example if the application has issued a verb that is not valid or failed to supply a required parameter), the user is not generally able to correct the problem; in these cases, the string is meaningful only to an application developer.
int WINAPI LOADDS GetAppcReturnCode (
long vcbptr,
unsigned int buffer_length,
unsigned char far * buffer_addr
);
The supplied parameters are:
A pointer to the VCB structure for the verb. This parameter is defined as a long integer, and so needs to be cast from a pointer to a long integer. For more information about the VCB structure and on its usage for individual verbs, see APPC Control Verbs or APPC Conversation Verbs.
The length (in bytes) of the buffer supplied by the application to hold the returned data string. The recommended length is 256 bytes.
The address of the buffer supplied by the application to hold the returned data string.
The return value from the function is one of the following:
The function completed successfully. The returned character string is
in the buffer identified by the buffer_addr parameter.
This string is terminated by a null character (binary zero), but does not
include a trailing new-line (
APPC could not read from the supplied VCB, or could not write to the supplied data buffer.
The supplied data buffer is too small to hold the returned character string.
The dynamic link library APPCST32.DLL, which generates the returned character strings for this function, could not be loaded.
|
|
|
 |
|