Two approaches to a DIGITAL ACMS solution are the following:

• Common applications
  The solution is common to both desktop systems and VT terminals.
• Tailored applications
  The solution involves multiple applications in which the tasks are tailored to either the desktop system or the VT terminal.

TP Desktop Connector software allows you to structure a common DIGITAL ACMS application to be accessed from both desktop systems and VT terminals. The task definitions, workspace definitions, task group definition, and application definition can be the same.

If users at both VT terminals and desktop systems in your enterprise need to run the same tasks, it is best to have a common DIGITAL ACMS application. This minimizes your development and maintenance work. If you use a presentation tool that is portable between DIGITAL OpenVMS and the desktop system, possibly no additional code is required to support the presentation software on both platforms.

To use NO I/O tasks in an environment that has both desktop systems and VT devices, you can take advantage of the task-call-task feature of DIGITAL ACMS. Divide common processing steps into standalone NO I/O tasks. The desktop client program calls these NO I/O tasks directly. The VT terminal users request I/O tasks that include exchange steps. These I/O tasks then use the task-call-task feature of DIGITAL ACMS to invoke the common NO I/O tasks as part of their processing steps. Any task error recovery within the common NO I/O tasks is shared by both presentation device types.

Maintenance increases slightly in this environment, because flow control is duplicated in the tasks called by the VT terminal users and within the desktop client program.

2.2.2.2 Tailored DIGITAL ACMS Applications

If your TP Desktop Connector solution does not include VT terminals, you can tailor the DIGITAL ACMS application and design the tasks somewhat differently from a common application. Use one of the following alternatives:

• Specify the NO TERMINAL USER I/O clause in the task definition, so that the ACMS tasks are NO I/O rather than I/O tasks.
• If you use FORM I/O or REQUEST I/O tasks, place more flow control in the desktop presentation code.
  DIGITAL ACMS applications that use DECforms or TDMS forms for VT presentation code can include a significant amount of flow control logic. Because you can write TP Desktop Connector presentation code in third-generation languages, you can include similar or more powerful flow control logic in the desktop client program, just as you include in DECforms or TDMS forms.
  However, the DIGITAL ACMS task definition is effective for representing the structure of a task clearly. For improved maintainability, represent the flow of a task in its definition rather than controlling the flow through its step procedures or its exchange steps.
• Have the desktop system focus on data capture, intermittently transmitting transactions to the DIGITAL ACMS system for processing as queued tasks.

These design approaches can also be applied to solutions that include both VT terminals and desktop systems. For example, to decrease network traffic, use a queued task model for the desktop systems and retain an interactive model for your VT terminals.

TP Desktop Connector software does not preclude optimizing the DIGITAL ACMS application for desktop systems and retaining a separate but comparable application for VT terminals. You can optimize the ACMS application by building separate desktop tasks within the same application definition or by building alternatives into the task definitions. However, carefully consider the additional maintenance cost required for such a solution.

2.2.2.3 Conversion of a Task: I/O to NO I/O

If you have I/O tasks and want to incorporate a desktop design in the application that does not depend on terminal interaction, you can convert the I/O tasks to NO I/O tasks. Converting an I/O task to a NO I/O task involves the following steps:

1. Delete the exchange steps.
2. Separate the processing steps into individual tasks.
3. Modify the action clause for each processing step to eliminate references to exchange steps.
4. Add a TASK ARGUMENTS clause for any workspaces used by a NO I/O task.
5. Add the NO I/O tasks to the task group definition.

Task conversion can be done without affecting anything else in the application. Section 8.6.3 contains an example of task conversion for the Macintosh sample.

2.2.3 Preventing Loss of Work with Local Data Capture

In some applications, desktop systems are most effective as relatively independent data capture resources. Users work with reference data stored locally on their personal computer, building up a queue of completed transactions awaiting their forwarding to a DIGITAL ACMS system. The desktop system signs in to the DIGITAL ACMS system and uploads the transactions from the desktop system to the DIGITAL ACMS system.

TP Desktop Connector software can effectively support the data capture model for desktop systems. Figure 2-1 shows how such a queue-based system can work.

Figure 2-1 Using a Queued Task with TP Desktop Connector

The TP Desktop Connector software does not directly provide queuing facilities, for example, services for data capture. The desktop client program can create and manage a file of transactions to be transmitted to the DIGITAL ACMS system. It also can determine when to establish the connection, such as at regular intervals, or when the queue reaches a predefined threshold. The desktop client program can then use the TP Desktop Connector client services to invoke tasks in a DIGITAL ACMS application that either process the queued items directly or run other tasks to move the items into DIGITAL ACMS queues on the DIGITAL ACMS system.

The TP Desktop Connector client services do not guarantee that an item queued on the desktop system is processed only once. If this guarantee is required, the application must supply a capability, such as having the receiver application check a queue item identifier for duplicates before storing a transaction.

2.2.4 Event-Driven Systems and the Nonblocking Environment

In event-driven systems like OSF/Motif and Microsoft Windows, a program is structured to include an event-dispatching mechanism (event dispatcher) and a collection of procedures that this dispatching mechanism invokes as the result of an event. Ideally, these procedures quickly return control to the event dispatcher so that other events are dispatched (or processed) without delay. If these procedures fail to return control quickly, slow and undesirable behavior in programs can result. This characteristic is especially true for Windows programs. When a procedure hangs in any given Windows program, the system cannot give control to another Windows program.

By providing nonblocking services, TP Desktop Connector software allows a desktop client program to release control to the event dispatcher (in Microsoft Windows, the message dispatching loop) without waiting for the DIGITAL ACMS system to respond. This nonblocking characteristic is particularly important when the network delays a response or the DIGITAL ACMS system performs extensive processing.

Because the release of control to the event dispatcher is so critical in event-driven systems (for getting user input, and so on), TP Desktop Connector supports nonblocking presentation procedures as well as the basic nonblocking client services.

For a description of forced nonblocking, see Chapter 7.

2.2.5 Nonblocking Design Considerations

Consider the following when designing your desktop client program for a nonblocking program and runtime environment:

• Return control to Windows
  In event-driven environments, structure desktop client programs to give up control to the event dispatcher as soon as all of the work is done and that it can be completed without a significant delay.
  • For service requests
    When requesting a nonblocking version of a TP Desktop Connector client service, promptly return control to Windows. The program does not wait for the server response to the request.
  • For presentation procedures
    When a presentation procedure request is received from the desktop gateway, return control to Windows promptly. The program does not wait to send a response to the gateway. To use Windows features such as dialog boxes for exchange step processing, the program must first return control to Windows to handle the user interaction with the dialog box.
• Establish a mechanism to poll for incoming TP Desktop Connector messages
  The desktop client program must supply and activate a procedure to periodically check for messages received from the gateway.

The AVERTZ sample applications for Motif and Microsoft Windows use a procedure to activate timer events so that pending TP Desktop Connector Gateway for ACMS messages can be processed. To process a timer event, the timer-event handler calls the TP Desktop Connector service acmsdi_dispatch_message to poll for and dispatch messages from the gateway.

2.2.6 TP Desktop Connector Gateway for ACMS Availability

Similar to distributed DIGITAL ACMS configurations for VT terminal users, a desktop system can connect a desktop client program to multiple submitter nodes that in turn invoke applications on application nodes. This can be achieved by using multiple copies of the desktop client program or a single copy initiating multiple DIGITAL ACMS sign-ins.

As discussed in Chapter 1, if the application node fails in a distributed configuration, the user can automatically be routed to another DIGITAL ACMS system on the next task selection. Having a submitter node responsible for sign-in distinct from a DIGITAL ACMS system that actually processes the application requests can provide a high degree of availability without any extra work in the desktop client program. For example, in Figure 2-2, if the application Node A fails, the TP Desktop Connector Gateway for ACMS can automatically reroute subsequent requests to Node B.

Figure 2-2 Application Node Failover Configuration

If the submitter node to which desktop users are currently attached fails, the TP Desktop Connector client services do not automatically route signed-in users to a new submitter node. This is true even if the user is connected to one of several nodes in a VAXcluster or VMScluster system. Because authentication of the user is performed on the submitter node, a failure of the submitter node invalidates the authentication of the user.

A desktop client program can provide failover for submitter nodes. Because a desktop client program can support multiple active sign-ins (though not multiple active tasks within a single sign-in), the user can have sign-ins active on multiple submitter nodes. The desktop client program explicitly signs the user in to several submitter nodes. If the primary submitter node fails, the desktop client program can sense the failure and switch to another sign-in. The user is already signed in to an alternative system and is ready to continue operations more rapidly. In this case, as shown in Figure 2-3, the desktop client program can be written to hide the submitter node failure from the user.

Figure 2-3 Submitter Node Failover Configuration

As with any DIGITAL ACMS solution, some application errors are handled directly by the DIGITAL ACMS software. For example, fatal errors that are not handled by customer-written server procedures can cause the DIGITAL ACMS system to cancel a task. In general, however, the TP Desktop Connector software returns any error it receives to the desktop client program. Therefore, the desktop client program can appropriately handle virtually all error conditions.

With TP Desktop Connector sign-in, task call, and sign-out, the desktop client program can trap the status returned by these operations and take appropriate action. The ACMSDI return status values identify conditions to which the desktop client program should respond. These conditions include sign-in failures, task processing errors, TP Desktop Connector Gateway for ACMS failures, and other error conditions. For example, ACMSDI_NORMAL is the return status indicating successful completion of TP Desktop Connector client services. If the ACMSDI_INTERNAL error is returned, the desktop client program should end any active tasks, sign the user out of the DIGITAL ACMS system, and instruct the user to exit from the application.

Error handling for exchange steps in I/O tasks is straightforward. When a DIGITAL ACMS task is canceled, the TP Desktop Connector Gateway for ACMS reports a specific error where possible. If the gateway cannot convert a DIGITAL ACMS error to a specific TP Desktop Connector status, it returns ACMSDI_TASK_FAILED to the desktop client program.

If the desktop client program encounters an error during its own processing of an exchange step, that error can be handled within the desktop client program. The desktop client program can then return status information in a workspace to be evaluated in the task definition for appropriate action. The desktop client program can also return any valid OpenVMS error code (including DECforms, TDMS, and application-defined values) to the DIGITAL ACMS system to instruct DIGITAL ACMS to continue or cancel the task.

2.2.8 TP Desktop Connector Gateway for ACMS Error Checking

The TP Desktop Connector Gateway for ACMS responds to recoverable thread-level errors by dropping the thread in a controlled way, causing that thread to be cleaned up while insulating other threads from any ill effects. The gateway treats some errors (such as access violations) as fatal to the gateway, thereby dropping all active threads.

These checks detect errors from the following sources:

• Network corruption
  If a network router corrupted packets, the gateway fails while trying to interpret the ill-formed messages, dropping all threads.

  Note TP Desktop provides the option of cyclic redundancy checking (CRC), which can detect this type of network corruption. See DIGITAL TP Desktop Connector for ACMS Gateway Management Guide for information on how to activate this feature.

• TP Desktop client program errors
  Client program errors can sometimes destroy or overwrite data that the TP Desktop client services send to the gateway. Typically, an ID value is destroyed. When the gateway detects the bad ID, TP Desktop disconnects that client, rather than causing the gateway to fail.

This section discusses the considerations in designing an effective user interface for your desktop client program. Some aspects of the interface, such as application flow, are discussed in Section 2.2. This section focuses on those questions that are most directly related to what the user sees on the display device.

Following these and other published user interface design principles can maximize user productivity:

• Consistency across applications
  As with any application, strive for a consistent user interface across applications, so that users do not have to learn new rules to do different kinds of tasks.
• Appropriate operating metaphors
  Provide a model for your interface that is familiar to your users. For example, just as using a map can help users efficiently locate an office, using an existing form as a model for a screen display can help users learn the application.
• Multiple sign-ins
  TP Desktop Connector software allows a desktop client program to establish multiple sign-ins to one or more DIGITAL ACMS systems. Having multiple sign-ins increases application availability, as discussed in Section 2.2.6. However, each sign-in increases network resource usage and consumes licenses. If the application has a large user base, the desktop client program might need to restrict the number of sign-ins allowed for each desktop system.
  A desktop client program that supports multiple sign-ins can also increase the user's ability to work effectively with complex functions. For example, complementary tasks can be available in different DIGITAL ACMS systems or in different applications on the same DIGITAL ACMS system. Each sign-in can be assigned its own window by the desktop client program. The desktop client program can run a task in each of these windows, allowing the user to cut and paste information from one window into another, or compare information in the two windows.
  Having the desktop code interact with NO I/O tasks rather than FORM I/O and REQUEST I/O tasks increases the usefulness of multiple active sign-ins. The greatest amount of control is retained on the desktop system. However, even with FORM I/O and REQUEST I/O tasks, having multiple active sign-ins can significantly increase the ability of the user to pull together many different tasks to perform a complex activity.
• Effective graphics use
  The presentation capabilities of the desktop environment are one of the great benefits of the desktop. Presentation tools that work within the desktop environment can provide significant benefits in the following areas:
  • Increasing clarity of information presented to the user
  • Structuring the presentation to increase the usability of the application
  • Tailoring the presentation to suit individual user needs
  
  Take advantage of presentation capabilities. However, because overuse of video attributes, fonts, and other features can be confusing, ensure that the presentation software contributes to the effectiveness of the application.
• Restricting user functions
  In event-driven environments, it is important for the user interface to restrict access to certain functions, such as by dimming icons. The design of the user interface must prevent the user from invoking tasks that are invalid under certain conditions. For example, the user interface needs to prevent a task from being invoked using a sign-in that is currently processing another task, and to prohibit signing out of the DIGITAL ACMS system when a task is being processed.

The ability to have presentation code native to desktop systems communicate with application code native to OpenVMS systems raises many new questions. The following sections discuss how the software handles differences in data types between the various environments.

2.4.1 Data Conversion

Because TP Desktop Connector software does not manipulate workspace contents, it does not constrain what data types are used on the desktop system or in the DIGITAL ACMS application. However, TP Desktop Connector software does not automatically handle data conversion between the OpenVMS and desktop environments. In many cases, you can build your desktop client program such that data types are compatible between the desktop system and the DIGITAL ACMS system. If you have incompatible data between the systems, the application code must perform any conversion required.

The most commonly used data types are readily mapped between OpenVMS and desktop systems. Part 2 contains sections that list the data types that must be converted for each platform.

For Macintosh systems, most nontext data requires conversion between the desktop client program and the gateway.

Typically, data conversion is done most effectively in the desktop client program. Doing so takes advantage of the processing power of the desktop system, and ensures the portability of the DIGITAL ACMS application.

2.4.2 Data Alignment with RISC Architecture Clients and OpenVMS Servers

The RISC architecture requires that data references be naturally aligned. That is, short words (2 bytes) must be on an even byte boundary. Long words (4 bytes) must be accessed on a boundary evenly divisible by 4.

When Alpha clients define a C structure, they create padding in the structure, if necessary, to ensure that each field complies with these requirements. (The padding is not visible to you.)

OpenVMS, however, does not impose such restrictions on its data objects and does not pad its structures. The problem arises when data, defined on one of these machines, is transmitted across the network to the other machine, and interpreted using the same C structure definitions.

In a TP Desktop application, this is a concern only when ACMS workspaces are being sent (in either direction) between the client program on a RISC machine such as DIGITAL UNIX Alpha and the ACMS application on OpenVMS.

Consider the following structure:

struct wksp_type { char field_1; short field_2; char field_3; } my_wksp;

On an Alpha client, my_wksp is stored as:

On an OpenVMS server, my_wksp is stored as:

If my_wksp is allocated on the OpenVMS server and sent to an Alpha client, the structure definition on the Alpha machine is expecting padding that is not there. At run time, your application on the Alpha machine generates the following message:

Fixed up unaligned data access for pid nnnn (appl_name) at pc 0xnnnnnn

One approach to dealing with this problem is to allocate new workspaces in the Alpha client program, and perform a byte copy of each field of the incoming OpenVMS server structure into the fields of the new client structure. For structures going from a RISC machine to OpenVMS, you also need to perform a byte copy of each field of the RISC structure to the outgoing data stream. If you are writing a portable application, this solution should not have an adverse effect when running on non-RISC platforms.

Example 6-9 and Example 6-10 show this approach from the AVERTZ Motif sample application.