| Previous | Contents | Index |
First, debug the presentation code on the desktop system. When the presentation code runs, debug the desktop client program with the DIGITAL ACMS software.
Follow these guidelines:
If you use a presentation tool that is portable between OpenVMS and the runtime environment, you can port the client program to OpenVMS. Porting of the desktop client program to the desktop system then involves relatively little work beyond rebuilding the executable images for the desktop client program and performing verification tests on those executable images.
This chapter describes developing nonblocking desktop client programs for event-driven, multitasking environments such as Microsoft Windows, Microsoft Windows 95, and Microsoft Windows NT. In this chapter, Windows refers to either Windows Version 3.1, Windows 95, or Windows NT. Examples in this chapter use Windows SDK Version 3.1 code to illustrate the use of DIGITALTP Desktop Connector nonblocking services in an event-driven environment. However, the same techniques can be used in other DOS event-driven environments.
You may also want to structure your application to use nonblocking services if you want to support multiple active sign-ins for failover, or multiple active tasks. Chapter 4 gives a useful background in the DOS TP Desktop Connector client services concepts and terminology. For information on designing your application with nonblocking services, see Chapter 2.
For information on configuring network transports for any of the client
platforms, see DIGITAL TP Desktop Connector for ACMS Client
Services Reference Manual.
5.1 Event-Driven Processing
A Windows desktop client program must yield control to the Windows manager as quickly as possible so that other event processing can be handled in a timely way. TP Desktop Connector nonblocking services provide methods to facilitate yielding control:
Figure 5-1 shows the sequence of processing in an event-driven desktop client program.
Figure 5-1 Event-Driven Desktop Client Program Processing
When the user selects a task from the menu, the desktop client program calls the acmsdi_call_task service to initiate a DIGITAL ACMS task. In the nonblocking environment, nonblocking parameters are specified in the call (see DIGITAL TP Desktop Connector for ACMS Client Services Reference Manual). One nonblocking parameter is the completion routine, which specifies a routine address in the desktop client program that the TP Desktop Connector client service calls when the TP Desktop Connector Gateway for ACMS completes the task. Because you specify the completion routine parameter in the call, the TP Desktop Connector client service returns control to the desktop client program immediately after the start task request is sent to the TP Desktop Connector Gateway for ACMS.
The desktop client program does not wait for the TP Desktop Connector Gateway to request DIGITAL ACMS software to start a task in a DIGITAL ACMS application. Instead, the desktop client program returns control to the Windows message-processing loop for more event processing.
The acmsdi_call_task service also returns a call identification that the desktop client program supplies to the acmsdi_complete_pp service. The services use the call identification to associate an active call with a submitter. A submitter uniquely identifies a sign-in. The acmsdi_sign_in returns the submitter ID to identify that connection or session for subsequent call-tasks and sign-out on behalf of that sign-in. In addition, the call ID, which uniquely identifies a task invocation, is passed to all of its related presentation procedures. Note that TP Desktop Connector supports, at most, one active task for each submitter.
Because of an exchange step in the I/O task, the DIGITAL ACMS system starts a transceive operation. The TP Desktop Connector Gateway sends a message to the desktop client program to start a presentation procedure.
Run as part of the control mechanism established by the desktop client program, the acmsdi_dispatch_message service polls for the message and, when the message is received, calls the customer-written presentation procedure acmsdi_transceive as shown in Figure 5-1. The acmsdi_transceive routine runs, displays a dialog box, saves pointers to the workspaces, and returns control to Windows without the user having signaled completion.
The user then has an opportunity to edit or add data to a form in the context of this exchange step. When the user later presses OK to signal completion, the desktop client program uses the workspace pointers to store the user-entered data, and calls the acmsdi_complete_pp service to send the response status to the TP Desktop Connector Gateway for ACMS. (The desktop client program does not wait for a response from the TP Desktop Connector Gateway. Generally, it returns control to the Windows message-processing loop as soon as possible.) Meanwhile, the TP Desktop Connector Gateway passes to the DIGITAL ACMS task any valid workspaces and the status from the completion of the presentation procedure.
When the task completes on the DIGITAL ACMS system, the TP Desktop Connector Gateway sends the end task message to the desktop system. The TP Desktop Connector client services dispatch the end task message by calling a completion routine in the desktop client program. This completion routine is dispatched by the polling mechanism and acmsdi_dispatch_message.
In this event-driven processing environment, the TP Desktop Connector Gateway sends a message to the desktop client program for the following reasons:
The TP Desktop Connector client services dispatch the TP Desktop
Connector Gateway messages to the desktop client program by the polling
mechanism established.
5.2 Guidelines for Developing Windows Desktop Client Programs
The following list summarizes general requirements and guidelines for developing Windows nonblocking desktop client programs as described in this chapter:
The following guidelines are optional when developing a nonblocking desktop client program:
If you are using Microsoft C, you can use the Programmer's WorkBench (PWB) supplied with the Microsoft C compiler. Compiling routines to include a Browser database of the desktop client-program source code provides helpful tracing and mapping capabilities similar to those provided by DIGITAL OpenVMS with Language-Sensitive Editor (LSE) and Source Code Analyzer (SCA).
The remainder of the chapter explains the guidelines using code from
the AVERTZ sample desktop client program.
5.3 AVERTZ Sample Desktop Client Program for Microsoft Windows
The AVERTZ sample desktop client program for the Windows environment is written in Microsoft C and follows the standards and practices outlined in the Microsoft Windows Software Development Kit (SDK) documentation. The program uses a main window, icons, and dialog boxes to interact with the user.
The program was developed with the PWB software that includes
mechanisms to aid debugging.
5.3.1 AVERTZ Components for Microsoft Windows
A Windows desktop client program has the same high-level components as a DOS application (see Figure 5-2). However, note the addition of the polling mechanism as well as how the application-specific presentation procedures are now broken into two parts. TP Desktop Connector supports, at most, one active exchange step per task call.
Figure 5-2 TP Desktop Connector Sample Components for Microsoft Windows
The AVERTZ.EXE program includes the following functional modules:
The desktop client program allows the user to maintain multiple sign-ins with the AVERTZ application, VR_DA_APPL. The program controls each sign-in by associating session context with the user sign-in data.
The desktop client-program user interface presents the following menus with which the user interacts to sign in to and out of the DIGITAL ACMS system, run DIGITAL ACMS tasks, and control sessions:
Program-defined icons represent sessions. The user can double click on
an icon to bring up the form for a specific session. The icons are also
visual clues to active and inactive sessions.
5.3.2 AVERTZ Component Processing Flow
The avertz.c module contains the Windows message-processing loop, program initialization, and main window function. The following important functions are performed:
The session.c module contains the following session creation and control functions:
The New command in the session menu presents a dialog box to enable the user to sign in to the DIGITAL ACMS system, thereby creating a new AVERTZ session. After the user is signed in to the DIGITAL ACMS system, the desktop client program maintains session information to track the association between a form or forms session and the corresponding DIGITAL ACMS submitter identification. The program also activates other menus to allow the signed-in user to select DIGITAL ACMS tasks. A session can have only one active task at any given time, but a user can sign in to the DIGITAL ACMS system many times, allowing multiple tasks to run simultaneously.
Individual modules handle the generic presentation procedures. For example, transw.c handles the acmsdi_transceive presentation procedure called from the DIGITAL ACMS system, validates the parameters, and dispatches control to the appropriate application-specific presentation procedure.
The avertzpp.c module handles all application-specific presentation procedures for the AVERTZ desktop client program. Each presentation procedure comprises an initial routine (for example, Trans_List2_List3) and a completion routine (for example, End_Trans_List2_List3). The generic presentation procedures call the initial routine (the first part of the presentation procedure), which generally displays the data from the workspaces sent by the DIGITAL ACMS system and returns. When the user signals completion (done entering data) for this presentation procedure, the corresponding completion routine is called. The completion routine collects the user-entered data and sends it to the DIGITAL ACMS system to complete processing of the presentation procedure.
The resvform.c module manages the reservation form for the reserve task, including field validation and initialization. The reserve routine handles Windows messages for the dialog boxes. (The reserve routine is the dialog function that Windows calls whenever the user interacts with the reservation form.) When the user clicks on the OK or cancel button in the reservation form, the reserve routine dispatches the completion routine of the current presentation procedure.
Chapter 6 describes this flow in a Motif environment. See
Figure 6-3, Figure 6-4, Figure 6-5, and Figure 6-6.
5.4 Writing Client Procedures Using Nonblocking Services
Procedures using nonblocking services must be structured as described
in the following sections.
5.4.1 Calling Nonblocking Services
Nonblocking forms of the services have the following differences from blocking forms:
Example 5-1 shows the calls in the session.c module to the acmsdi_sign_in service that creates a new session, and to the companion completion routine NewSession_Complete that completes the service. The desktop client program calls the message dispatcher to check for pending replies or requests from the TP Desktop Connector Gateway. When a completion message for a client service arrives, the message dispatcher calls the completion routine in the desktop client program.
| Example 5-1 Nonblocking Service Call and Completion Routine |
|---|
BOOL FAR PASCAL NewSession(
HWND hDlg, /* window handle of the dialog box */
WORD message, /* type of message */
WORD wParam, /* message-specific information */
LONG lParam)
{
.
.
.
status = acmsdi_sign_in(
session_ptr->node,
session_ptr->username,
session_ptr->password,
(long) 0,
session_ptr->submitter_id,
&session_ptr->completion_status,
NewSession_Complete, (1)
(void *) session_ptr);
if (status == ACMSDI_PENDING) (2)
{
.
.
.
void NewSession_Complete(void *call_context) (3)
{
session_type *session_ptr;
List session_node;
char session_button_title[MAX_STRING_LENGTH];
int x;
HWND SessionIcon;
int i;
/* Get Session Node For This Sign In Completion */
session_ptr = (session_type *) call_context;
/*
** Check ACMS Return Status
** - If failure occurred, delete session from session list and
** put up a message.
*/
if (session_ptr->completion_status != ACMSDI_NORMAL)
{
DisplayDesktopErrorMessage(session_ptr, session_ptr->completion_status);
.
.
.
|
The user triggers the call to the acmsdi_sign_in service by selecting the OK button on the New Session dialog box. The numbers in Example 5-1 correspond to the following explanations:
After the acmsdi_sign_in service returns ACMSDI_PENDING, the desktop
client program receives a
submitter identification that is used on subsequent
calls. If a nonblocking call to a TP Desktop Connector service routine
returns a status code other than ACMSDI_PENDING, the completion routine
for that call is not invoked.
5.4.2 Setting Up Polling
In a nonblocking environment, the desktop client program must initiate a control mechanism to poll for pending DIGITAL ACMS messages. To set up polling, the desktop client program does the following:
The acmsdi_dispatch_message service polls for messages from the TP Desktop Connector Gateway and calls the appropriate customer-supplied completion routine or presentation procedure, depending on the type of TP Desktop Connector message received. Example 5-2 shows the sample coding sequence from the avertz.c module.
| Example 5-2 Setting Up Polling |
|---|
int PASCAL WinMain
{
.
.
.
client_init; (1)
.
.
.
long FAR PASCAL MainWndProc
switch (message)
{
case WM_TIMER:
if (wParam == DESKTOP_MESSAGE_TIMER)
{
acmsdi_dispatch_message; (2)
}
break;
.
.
.
}
.
.
.
void client_init(void)
{
SetTimer(
hWndMainWindow,
DESKTOP_MESSAGE_TIMER, (3)
MESSAGE_CHECK_FREQUENCY,
NULL);
}
|
Example 5-2 shows the following steps from the module avertz.c:
To notify the desktop client program that a TP Desktop Connector message from the gateway is pending, the acmsdi_dispatch_message service calls a customer-supplied completion routine or a generic presentation procedure.
| Previous | Next | Contents | Index |