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:

• Sign a user in to an ACMS system
• Run ACMS tasks
• Sign the user out of the ACMS system

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:

• In the blocking environment, the desktop client program calls a TP Desktop client service and is blocked awaiting a message from the TP Desktop Connector gateway.
• With the nonblocking versions of the portable client services, the desktop client program calls a TP Desktop client service, specifying a completion routine. The program regains control without having to wait for a message from the TP Desktop Connector gateway. When an TP Desktop message is received from the TP Desktop Connector gateway, the completion routine is called.
• The forced nonblocking environment allows presentation tools like Visual Basic and PowerBuilder to issue nonblocking calls even though these tools do not support pointer types to handle arguments passed by reference.

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:

• Initialization phase
  During the initialization phase, a desktop client program creates necessary data structures and performs activities such as setting up the user interface and establishing a message-polling mechanism.
• Sign-in phase
  During the sign-in phase, a desktop client program establishes one or more sessions with the same TP Desktop Connector gateway or with different TP Desktop Connector gateways.
  The TP Desktop Connector gateway performs these functions:
  1. Authenticates the user for user name, password, time of day, and other OpenVMS login characteristics.
  2. Authenticates the user for ACMS sign-in.
  3. Assigns a unique session identifier that allows the desktop client program and the user to distinguish among multiple connections to one or many ACMS systems by one desktop user.
  
  A desktop client program can have multiple active sign-ins, however, a user can have only one task active for each sign-in.
• Task-selection phase
  During the task-selection phase, a desktop client program requests an TP Desktop client service to start a task in an ACMS application. The service sends a request to the TP Desktop Connector gateway to select the task.
• Task-processing phase
  During the task-processing phase, the ACMS system does the following:
  1. Checks the task access control list (ACL).
  2. Begins processing the task.
  3. Dispatches processing steps to procedure server processes.
  4. Dispatches exchange steps to the TP Desktop Connector gateway for transmission to the desktop client program.

  5. Determines task flow based on control information returned on each step.
  6. Completes the task and sends a response to the desktop client program.
• Sign-out phase
  During the sign-out phase, a desktop client program must sign the user out of the ACMS system. On the desktop system, the desktop client program calls an TP Desktop client service, which does the following:
  1. Sends a request to the TP Desktop Connector gateway to sign the user out of the ACMS system.
  2. Disconnects the network logical link for that session.

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:

• Develop the desktop client program within the desktop environment using desktop programming languages and tools.
  Frequently, this best ensures that the desktop client program takes full advantage of the capabilities unique to specific desktops.
• Develop the desktop client program within the OpenVMS environment, using languages and tools portable between OpenVMS and desktop systems. Move the source code to the desktop system to compile, link, and debug the program using desktop tools.
  The Macintosh TP Desktop client services are not portable to the OpenVMS system.

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, Tru64 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 Compaq TP Desktop Connector for ACMS Client Services Reference Manual.

See Compaq TP Desktop Connector for ACMS Gateway Management Guide for information on managing TP Desktop systems and using the TP Desktop system management services. Also, Compaq 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.

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 Compaq ACMS design in general, refer to the documents in the 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 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 Compaq 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.

Compaq 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:

• Design, build, and test the ACMS parts of the solution before building the presentation code.
• Start with the presentation code. After you build an effective user interface, implement the ACMS parts of the 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, ACMS tasks fall into two categories:

• NO I/O (processing only) tasks
  This category of task has the NO TERMINAL USER I/O clause in the task definition. It is written to include only processing steps. The task itself does not specify input or output to the user; rather, the interaction with the user occurs outside the task. Any information required within the task or to be returned by the task is passed as task arguments. That is, workspaces declared for the task are passed as parameters on the call to the task and on the return from the task.

• I/O tasks
  This category of task has either the FORM I/O clause or the REQUEST I/O clause in the task definition. For applications that support VT terminals, most task definitions include both exchange steps and processing steps. In these tasks, interaction with the user is typically performed in the exchange steps of the task, using DECforms software, TDMS, or other presentation tools.

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 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 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 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 ACMS task depends on the following factors:

• The desktop system in use
• Whether the desktop client program uses the blocking or nonblocking form of the services and presentation code