DIGITAL TP Desktop Connector
for ACMS
Client Application Programming Guide


Previous Contents Index

1.2 Desktop Client Program Processing

This section describes TP Desktop client services, program action routines, and general processing phases.

1.2.1 TP Desktop Client Services

The TP Desktop client services are callable routines that allow the desktop client program to do the following:

These routines are shown as TP Desktop client services in Figure 1-2.

The desktop client program can run in a blocking, a nonblocking, or a forced nonblocking environment:

The nonblocking services are designed for multitasking event-driven systems like Microsoft Windows or OSF/Motif.

The TP Desktop client services for the Macintosh run in the blocking environment during ACMS sign-in and sign-out. The services support nonblocking task execution.

1.2.2 Desktop Client Program Action Routines

TP Desktop software supports predefined action routines for checking versions of software on the desktop system. The desktop client program can provide a routine to check application-defined version information supplied from the system running the TP Desktop Connector Gateway to ensure that software versions are compatible. See Section 4.3 for information on writing version-checking routines.

1.2.3 Phases of Desktop Client Program Processing

A desktop client program passes through several processing phases:

Figure 1-4 illustrates the processing phases of a client program.

Figure 1-4 Desktop Client Program Processing Phases


Because of the authentication required during the sign-in phase, it is typically more efficient to have users remain connected across multiple task-selection and task-processing phases. The task-selection and task-processing phases repeat until the desktop client program explicitly requests to end the session.

1.3 Programming with TP Desktop Software

The TP Desktop software supports the following approaches for developing the desktop client program for an ACMS application:

You can take advantage of expertise on one platform rather than maintain expertise across multiple platforms. For example, a desktop client program, written for the DOS system using portable tools, can also be run on the OpenVMS system. The programming interface for the TP Desktop client services for the OpenVMS system is the same as that for DOS. If the programming language and presentation tool are portable between OpenVMS and DOS systems, less in-depth expertise for the DOS system is required to create effective desktop client programs. With this approach, you can also take advantage of testing source control software available on the OpenVMS system.

In developing portable applications, you must still take into account certain differences between operating systems even if you are using portable tools.

Chapter 2 introduces the key design issues to consider in using TP Desktop software effectively. Later chapters describe how to build a desktop client program using each of the approaches outlined above, and explain the details of the TP Desktop client services and presentation code.

1.4 System Management with TP Desktop Software

For DOS and Macintosh systems, PATHWORKS software is used both in the communication portion of the TP Desktop Connector product and in the management of solutions implemented using TP Desktop software. For example, the TP Desktop installation places all files in OpenVMS directories, including those for the TP Desktop client services. PATHWORKS tools are then used either to distribute the software to the desktop systems or to make it available to the desktop client programs through file server capabilities.

For OpenVMS systems, network file transfer tools are used to copy the TP Desktop client software to the desktop system. PATHWORKS is optional for Macintosh, OpenVMS, DIGITAL UNIX, and Windows NT client programs.

TP Desktop software provides the ACMSDI$GET_SUBMITTER_INFO system management service for OpenVMS and a sample program demonstrating its use. This service can be used in utility programs running on the server to retrieve information about users currently connected to an ACMS system through TP Desktop software. The information returned by this service is necessary when the system manager needs to cancel a desktop client program session.

For documentation on the service and the location of a sample program that uses this service, see DIGITAL TP Desktop Connector for ACMS Client Services Reference Manual.

See DIGITAL TP Desktop Connector for ACMS Gateway Management Guide for information on managing TP Desktop systems and using the TP Desktop system management services. Also, DIGITAL TP Desktop Connector for ACMS Installation Guide describes those aspects of system management related to installing TP Desktop.

1.5 TP Desktop Sample Application

Sample desktop client programs provided with TP Desktop software are based on the vehicle rental application called AVERTZ. The TP Desktop version of the sample includes similar tasks and procedures as the ACMS version of AVERTZ. This sample application illustrates the use of TP Desktop software to create multiplatform solutions supported by a common ACMS application.

This manual discusses design and development issues in the context of this sample. The sample desktop client programs illustrate many of the most common design considerations and provide a base of code from which you can build your solution. Most of the code shown as examples is taken from the AVERTZ sample application.

The sample desktop client programs are a key resource for understanding how to design and implement TP Desktop solutions. The software distribution kit contains sources and executables for each supported desktop system. After installation of the TP Desktop kit, you can find the source code on the OpenVMS system on which the kit was installed. Appendix A lists the directories containing the sample code.

The installation documentation describes how to set up and run the sample application on the host and the desktop systems. You can examine in detail how the various issues in building a complex, multiple-environment system are addressed in at least one solution. The samples are not intended as production applications. However, they help illustrate how to use TP Desktop software.


Chapter 2
Designing TP Desktop Connector Solutions

This chapter outlines the major considerations in designing a TP Desktop Connector solution. The focus is on those areas that relate specifically to using the TP Desktop client services.

For a discussion of DIGITAL ACMS design in general, refer to the documents in the DIGITAL ACMS documentation set listed in the Preface section titled Related Documents.

2.1 TP Desktop Connector for ACMS Design Questions

In designing solutions that use DIGITAL TP Desktop Connector software, you face significant design issues such as those listed in Table 2-1.

Table 2-1 Design Issues
Category Issues
Processing Structuring the desktop client program code
Handling errors
Implementing flow control
User interface design Choosing presentation software
Using graphics and other display tools effectively
Handling multiple sign-ins
Data design Data conversion
Local caching of data
Data compression
Ensuring data integrity
Handling validation

Some key issues, such as the choice of presentation software, span these categories. These issues are discussed in the following sections.

2.1.1 Understanding Application Requirements

Most important in ensuring an effective design is understanding what you are trying to build. The requirements of the application in such areas as performance, expense, usability, availability, data integrity, manageability, and maintainability may force you into difficult tradeoffs. The requirements you are addressing can interact or conflict. For example, you may want to increase message buffer size to improve network performance, but this forces you to consider adding memory to the machines, which increases cost.

A solution that meets requirements in one area can fall short of requirements in another. For example, an application that caches much information locally can have extremely good performance on tasks with local validation. But it can be costly in management overhead and network traffic to keep the validation data updated. Or an application that captures transactions and invokes only NO I/O tasks for periodic transmission of the transactions to a DIGITAL ACMS system may have exceptional availability. But it can restrict the kinds of validation available on the desktop system and, therefore, decrease the overall usability of the system.

Having explicit requirements for your application increases your ability to create an effective design. If you must trade off one requirement over another, you have better information with which to make your trade-offs.

2.1.2 Choosing Presentation Software

The presentation tool you choose can have a major impact on other design issues. For example, the presentation capabilities available in COBOL can be adequate for many DOS applications. A portable tool like COBOL provides development benefits that may outweigh limitations in the application's user interface. On the other hand, different screen management tools on the market provide significant enhancements to the user interface, though at the cost of additional expertise required of the development staff.

Digital recommends that you prototype at least part of your solution and then begin major development. Prototyping helps ensure that you understand any design issues unique to that tool before you begin implementation. It also helps to uncover any issues that might arise in using that tool in TP Desktop presentation code.

2.1.3 Understanding Memory Constraints

Many design considerations, especially for DOS systems, reflect that desktop systems are often configured with limited memory. If users of your application typically have systems with abundant memory, you can take advantage of the added memory as you design the overall application. However, designing an application to require extra memory can prevent desktop systems with less memory from running that application.

2.1.4 Strategy for Implementing the Solution

You can take either of the following approaches to implementing your solution:

TP Desktop software supports both of these approaches equally well. Whichever approach you choose, ensure that the sequence and the context of messages represented by the task definitions are understood and handled by your presentation code.

2.2 Processing Design

This section explores the major considerations in designing the processing for solutions using TP Desktop Connector software. Part 2 describes how you structure desktop client programs for each platform.

2.2.1 NO I/O and I/O Tasks

From the point of view of the desktop client program, DIGITAL ACMS tasks fall into two categories:

2.2.1.1 NO I/O Task and TP Desktop Connector Interaction

Example 2-1 shows a task definition and annotations describing how the task statements are handled.

Example 2-1 NO I/O Task Actions for TP Desktop Connector Users

REPLACE TASK employee_lookup               
USE WORKSPACES                             
  employee_number,                         
  employee_record;                         
TASK ARGUMENTS ARE 
  employee_number WITH ACCESS READ,  (1)
  employee_record WITH ACCESS MODIFY;         
BLOCK WORK WITH NO TERMINAL I/O  (2)
 PROCESSING                                        
 get_employee: 
        PROCESSING WORK 
          IS CALL PROCEDURE get_employee (3)
             IN SERVER employee_server 
             USING  employee_number, 
                    employee_record;       
END BLOCK WORK;                            
END DEFINITION;   (4)

The annotations in Example 2-1 indicate the following:

  1. The task arguments are workspaces passed to and received from the desktop client program.
  2. The task is declared to have no terminal I/O.
    NO I/O tasks have no exchange steps, with the NO TERMINAL USER I/O clause specified for the block.
  3. The task calls server procedure get_employee in the DIGITAL ACMS application.
  4. The task returns workspaces with possible changes to the desktop client program.

TP Desktop Connector software handles each NO I/O task by accepting workspaces and other arguments from the desktop client program at the start of the task, and sending workspaces and other arguments to the TP Desktop Connector client services at the end of the task.

2.2.1.2 I/O Task and TP Desktop Connector Interaction

TP Desktop Connector supports tasks that have exchange steps as well as tasks that have only processing steps. TP Desktop Connector software handles each exchange step by sending task workspaces and other arguments between the TP Desktop Connector client services and DIGITAL ACMS by means of the TP Desktop Connector Gateway for ACMS. Example 2-2 shows a task definition and annotations describing how the task statements are handled.

Example 2-2 I/O Task Actions for TP Desktop Connector Users

REPLACE TASK employee_lookup               
USE WORKSPACES                             
  employee_number,                         
  employee_record;                         
BLOCK WORK WITH FORM I/O  (1)
 IS                                        
 get_employee_number:                      
        EXCHANGE WORK IS                   
         RECEIVE FORM RECORD get_employee_key (2)
           IN FORM employee_form 
           RECEIVING employee_number; 
 get_employee:                             
        PROCESSING WORK 
          IS CALL PROCEDURE get_employee (3)
             IN SERVER employee_server 
             USING  employee_number, 
                    employee_record;       
  display_employee:                        
        EXCHANGE WORK IS                   
         SEND FORM RECORD display_employee_record (4)
          IN FORM employee_form 
          SENDING employee_record; 
END BLOCK WORK;   
END DEFINITION;                    (5)

The annotations in Example 2-2 indicate the following:

  1. The task is declared with the FORM I/O clause.
    This indicates that DECforms syntax is used for the exchange steps.
  2. A request is received from the user.
    For TP Desktop Connector users, the task receives workspaces and workspace counts from the desktop client program through the TP Desktop Connector client services.
    For nondesktop users, the DECforms request FORMS$RECEIVE is called by ACMS.
  3. The task calls procedure get_employee in the DIGITAL ACMS application.
  4. A response is sent to the user.
    For TP Desktop Connector users, the task sends workspaces and status information to the desktop client program through the TP Desktop Connector client services.
    For nondesktop users, the DECforms request FORMS$SEND is called by ACMS.
  5. The task ends.

The format of the interaction between the desktop client program and the DIGITAL ACMS task depends on the following factors:

2.2.1.3 Choosing Between I/O and NO I/O Tasks

TP Desktop Connector software allows you to call I/O tasks (FORM I/O and REQUEST I/O) and NO I/O tasks (NO TERMINAL I/O) from a desktop client program. Choosing between I/O and NO I/O tasks is a choice of where to place control of the application flow. With I/O tasks, the task controls the application flow. With NO I/O tasks, the client program controls the application flow.

If the application supports only desktop systems or you are optimizing the DIGITAL ACMS application for desktop access, consider using only NO I/O tasks.

NO I/O tasks fit better with event-driven desktop systems, such as Microsoft Windows and Macintosh systems. With these systems, the desktop client program rather than the DIGITAL ACMS application controls the major processing flow.

NO I/O tasks also allow the greatest freedom in handling the logic in the desktop client program. However, task invocation can be more expensive than invoking processing steps within a task. Each task invocation requires workspace management by the DIGITAL ACMS Application Execution Controller (EXC), which is considerably more expensive in processor time than the workspace management done for exchange steps. Also, the DIGITAL ACMS system requires processor time to set up control structures when the task starts and to clear the structures when the task ends.

The additional central processor usage for task invocation compared to processing step invocation is generally small. However, the extra overhead for task invocation can be a significant factor in a system with high throughput requirements.


Previous Next Contents Index