TP Desktop software does not provide a mechanism for data validation on the desktop system. If you want to cache data on the desktop system for functions such as range checks and choice lists, the application must be responsible for handling the distribution of data to the desktop system. The application must also handle the updating of the local data to ensure that it is up to date.

In many cases, the validation on the desktop system can be restricted to fairly static and unchanging data. For example, a list of geographic codes can be built as an external table referenced by the desktop client program with minimal concern. Less static information, such as part numbers, employment codes, and site locations, might nonetheless be stable enough so that you can distribute revised information easily. It is valuable to have as much of this validation on the desktop system as possible. DOS or Macintosh desktop users can take advantage of PATHWORKS tools to copy updated tables when they are available. DOS desktop client programs can also use the TP Desktop version-checking capability to ensure that the tables are current.

Caching of more dynamic information is also possible. However, it is difficult with currently available tools to ensure consistency between highly dynamic data on the desktop system and data in a DIGITAL ACMS system.

2.4.4 Data Integrity

Like DIGITAL ACMS software, TP Desktop software generally relies on the data management systems employed in the DIGITAL ACMS system to ensure the integrity of data. For example, the transaction semantics of database and distributed transaction software ensures that all activities within a transaction are atomic. TP Desktop relies on the locking capabilities of database software to ensure that all activities within a database transaction are serialized and that they can be rolled back, if necessary.

In most cases, complex update transactions imply displaying data to the users, allowing them to change it, and then applying those changes to the database. The cost of locking the data while the user looks at and modifies it is typically prohibitive. Therefore, other mechanisms are generally employed in the application code to allow the locks to be released during this user interaction. For example, to ensure that the software can detect changes made by another user while the lock is released, a copy or a sequence number of the original data is retained.

TP Desktop software does not alter the data integrity strategies normally used with DIGITAL ACMS systems. The same issues must be addressed, and the same solutions generally apply. The areas in which desktop solutions may be more restricted are in queued transactions and in local caching of data discussed in Sections 2.2.3 and 2.4.3. Tools that are available in homogeneous OpenVMS solutions, including distributed solutions, can provide a level of data integrity for OpenVMS solutions that is not available to solutions involving multiple platforms.

2.4.5 Workspace Design

As with distributed DIGITAL ACMS systems, the factor having the single greatest effect on application response time is typically the size of the messages being sent over the network. In an TP Desktop system, all message traffic during task processing is based on the workspaces defined for the task. To minimize the cost of network data transfer on each task invocation, exchange step, and task end, design the application workspaces with the following guidelines:

• Take advantage of unidirectional workspaces for client programs.
  TP Desktop lets you specify whether a workspace containing task arguments is sent from the client to the gateway (read-only), from the server to the client (write-only), or in both directions (modify). Using read or write access reduces the overall network cost of the task. Note that the read and write are from the perspective of the server. See Section 2.4.5.1 and Section 8.1.10 for more information about unidirectional workspaces.
• Take advantage of DECforms syntax in task definitions.
  Using DECforms syntax in the exchange steps allows different size workspaces in send and receive messages. Other syntax requires that workspaces be the same size in both directions.
• Keep the workspaces as small as possible.
  In tasks with great variations between data sent in one exchange step and data sent in another, create separate workspaces for each step rather than reusing a single workspace.
• Minimize the number of workspaces.
  A small incremental cost exists for each workspace transmitted either as a task argument in a NO I/O task or as data on an exchange step. For task arguments and exchange steps, use as few workspaces as possible, keeping each workspace and the total data sent as small as possible.
• Transmit a usable amount of data.
  In tasks that allow users to scroll through large amounts of data, return the data one page at a time. By caching each page on the desktop system as it is sent, you can ensure that the desktop client program does not have to return to the DIGITAL ACMS system to retrieve data already sent. With this approach, you ensure that users do not have to wait for numerous relations to be read from the database and sent to the desktop client program when the information they need is in the first relation.
• Compress task argument workspaces.
  TP Desktop supports compression on task argument workspaces. See Section 2.4.6 for information on compression.
• Take advantage of data definitions.
  If the data is drawn from multiple relations in the database, the workspace definitions may not map to database relations. However, you can base workspace definitions on the same field definitions that make up the database tables.

For TP Desktop performance, the most critical issue is to balance the workspace size and the number of workspaces. Minimize both the amount of data transferred in each message between the desktop system and the DIGITAL ACMS system and the number of messages being sent.

2.4.5.1 Unidirectional and Bidirectional Workspaces

TP Desktop provides a mechanism, called unidirectional workspaces, by which you can control how data is sent across the network. With unidirectional workspaces, only those workspaces that actually contain data need to be sent in either direction. Bidirectional workspaces send data in both directions. By specifying which workspaces need to go in one direction only, the application can significantly reduce unnecessary network traffic.

TP Desktop provides three types of workspaces, two of which are unidirectional:

• Read-only (undirectional)
  Read-only workspaces contain data that the client application needs to send to the ACMS task. The task needs to receive the data, but it does not need to update the workspace (or write into it). Therefore, you need to send read-only workspaces only in one direction: from the client application to the task.
  Read-only means that these workspaces are read-only from the server's perspective. This meaning is consistent with the ACMS task definition syntax.
• Write-only (unidirectional)
  Write-only workspaces contain data that the task needs to send to the client application. The client application does not send data in these workspaces to the ACMS task. The ACMS task writes values into these workspaces to send back to the client application. Therefore, you need to send write-only workspaces only in one direction: from the ACMS task to the client application.
  These workspaces are write-only from the server's perspective. This meaning is consistent with the ACMS task definition syntax.
• Modify (bidirectional)
  Modify workspaces contain data that the task needs to send to the ACMS task. The ACMS task:
  • Uses the data in these workspaces.
  • Makes updates to the workspaces.
  • Returns the updated workspaces to the client application.
  
  Therefore, you must send modify workspaces in two directions: from the client application to the ACMS task, and from the ACMS task back to the client application.

The modify workspace is the default. If you do not specify the access type of the workspace to pass, TP Desktop sends all the workspaces that are passed to it in both directions.

You specify the access type of the workspace on the call to the acmsdi_call_task client service. See DIGITAL TP Desktop Connector for ACMS Client Services Reference Manual for information on the acmsdi_call_task client service. For information on passing unidirectional workspaces with Visual Basic or with Macintosh systems, see Chapter 7 and Section 8.1.10, respectively.

2.4.6 Data Compression

TP Desktop provides compression for task argument workspaces; workspaces on exchange steps are not compressed by any TP Desktop service. However, TP Desktop client services can accept compressed exchange-step workspaces and can decompress them before passing them to client applications. This section presents the call options required to compress task argument workspaces. Section 4.2.5 describes how to use compression with the Portable API.

The following rules apply to TP Desktop data compression:

• Data compression for task argument workspaces are initiated by the client application in the form of requests to the client services layer.
• Compression and decompression of exchange step workspaces are transparent to the client application.
• Data compression is activated for a call. Once activated, compression can be requested on a workspace-by-workspace basis.
• Although the client application can request compression for individual workspaces, the application never sees a compressed workspace, nor does the client application have access to the algorithm being used for compression.
• If compression is requested for a MODIFIABLE workspace, attempts are made to compress that workspace in both directions.
• The client services layer attempts to compress READ-ONLY and MODIFIABLE workspaces, if requested.
• The client services layer passes the application's compression requests to the back-end for MODIFIABLE and WRITE-ONLY workspaces, which causes ACMS to attempt to compress those workspaces.
• A compression attempt on a workspace can result in the total workspace size, including workspaces header data, being equal to or greater than the original, uncompressed, workspace size. If this is the case, the client services layer sends the workspace in its uncompressed form. The client application is not informed when this happens.
• If compressed workspaces are sent to an ACMS system, which does not support data compression, the gateway rejects the task call with a special error message.

The design issues discussed in this chapter are highly dependent on the design of the solution as a whole. For example, although applications should generally avoid using large workspaces, a given application can have excellent reasons for using them. By understanding all your own application requirements, you can decide on each of the issues raised in this chapter.

The design topics discussed in this chapter focus on desktop issues. Larger issues concerning the entire application environment are equally important. For example, if the data storage and access design of the DIGITAL ACMS system results in slow response time, that can have as immediate and visible an effect on the user interface as any decisions about presenting data to the user on the desktop system. Likewise, confusing flow control is a problem whether it is embedded in the task definition or in application-specific presentation code.

In creating a desktop solution, be sure to pay close attention to these larger issues, as well as the desktop-specific concerns. See the documentation for ACMS, Oracle CDD, Oracle Rdb, and other related products for information on these other areas of application design.

This chapter presents guidelines for development work you do on the DIGITAL OpenVMS system for use with desktop client programs.

3.1 Overall Development on the OpenVMS System

Some elements of your TP Desktop Connector solution must be developed and run under OpenVMS software, regardless of where you develop your presentation code. One of the key elements of the solution is the ACMS application called by your desktop client programs. To create the ACMS application, do the following on the OpenVMS system:

1. Create and populate the databases that your DIGITAL ACMS applications access.
2. Create definitions for the tasks in your DIGITAL ACMS application and workspaces for these tasks.
3. Write step procedures for the processing steps in your tasks.
4. Write task group and application definitions.
5. Build the task group and application database.
6. Link the procedure server image.

In developing these elements of your desktop solution, you perform exactly the same steps as in developing DIGITAL ACMS solutions that do not use TP Desktop Connector software.

Refer to the DIGITAL ACMS documentation listed in the Preface section titled Related Documents.

If your solution includes both VT terminals and desktop devices, create the presentation code for the VT terminals on the OpenVMS system.

If you are not using VT devices and are using FORM I/O or REQUEST I/O tasks, do not build the DECforms form libraries or TDMS request libraries for the exchange steps in your task definitions. See Section 3.3.

3.2 Creating Data Definitions for the Desktop System

The maintenance cost of the DIGITAL ACMS solution can be reduced by having common data definitions in the DIGITAL ACMS application and in the desktop client program.

To ensure common data definitions, create include files for the languages being used as follows:

1. Define workspaces in Oracle CDD software (using the Operator utility CDO).
2. From the Oracle CDD definitions, create an include file in each third-generation language in which your desktop client program is written:
   1. Create a dummy OpenVMS program that includes or copies the Oracle CDD definitions from the dictionary.
   2. Compile the dummy program to extract the definitions and create a listing file with their language equivalents.
   3. Edit the listing file and extract each definition to create an include file.
3. Ensure that the include files are compatible with the desktop compiler you are using.
   For example, replace underscores in Microsoft COBOL with dashes, and convert the data type int in VAX C to long int for Microsoft C.

The include files are for use in the presentation code on the desktop systems. For example, if the desktop client program is written in C and COBOL, create the source files for both languages.

3.3 Treating Forms in Task and Task Group Definitions

Generally, task and task group definitions are not dependent on whether an application handles VT or desktop devices. However, if you are using FORM I/O or REQUEST I/O tasks, the treatment of forms in the task and task group definitions depends on whether the DIGITAL ACMS application runs without VT devices.

If you are using VT and desktop devices and either FORM I/O or REQUEST I/O tasks, refer in the task definitions to the real form name or names and in the task group definition to the real .FORM or .RLB file used by the DIGITAL ACMS application.

If you use the FORM I/O or REQUEST I/O attribute in your desktop-only task definitions (as opposed to using tasks with the NO TERMINAL USER I/O attribute), the task and task group definitions must still refer to actual files. This reference is necessary because the EXC opens these files when the DIGITAL ACMS application starts.

You can use names supplied by Compaq if you do not want to create your own:

• In the task definition, refer to ACMSDI_FORM as the form name.
• In the task group definition, refer to a form library file or a request library file:
  • SYS$LIBRARY:ACMSDI$FORM.FORM for FORM I/O tasks
  • SYS$LIBRARY:ACMSDI$RLB.RLB for REQUEST I/O tasks

The TP Desktop Connector software provides an empty but valid form library file and a request library file to which the task group definition can refer. These files are created when you install TP Desktop Connector software on an OpenVMS system.

Example 3-1 shows definitions of a task and a task group that refer to the file ACMSDI$FORM.FORM.

Example 3-1 Desktop-Only I/O Task and Task Group Definitions

REPLACE TASK sample_task WORKSPACES ARE sample_wks1, sample_wks2; BLOCK WORK WITH FORM I/O (1) EXCHANGE TRANSCEIVE RECORD sample_rec1, sample_rec2 IN acmsdi_form SENDING sample_wks1 (2) RECEIVING sample_wks2; . . . END BLOCK WORK; END DEFINITION; REPLACE GROUP sample_group USERNAME IS sample_exc FORM IS acmsdi_form IN "sys$library:acmsdi$form.form" (3) WITH NAME acmsdi_form; SERVER IS sample_server: DCL PROCESS; END SERVER; TASK IS sample_task: TASK DEFINITION IS sample_task; END TASK; END DEFINITION;

The following are the key points in Example 3-1 for a DIGITAL ACMS application without VT devices:

1. A task definition with FORM I/O signals the requirement for a DECforms form name.
2. The name ACMSDI_FORM refers to the DECforms form supplied with this product.
3. The task group definition shows the full specification for the DECforms form file supplied with this product.

If your desktop client program uses the portable client services, which support version checking, you can build a program to run on the OpenVMS system to pass version information to the desktop client program. See Section 4.3 for information on the processing support for version checking. For version checking with the Macintosh client services, see Section 8.1.11.

Your ACMSDI_GET_VERSION routine can do one of the following checks:

• Look at your DIGITAL ACMS application images to determine versions.
• Use a version number stored in the application database.
• Take other approaches to establish the version of the DIGITAL ACMS application software.

The routine returns a value in its version parameter, a 24-character string.

To do version checking, perform the following operations on the OpenVMS system:

• Link your ACMSDI_GET_VERSION routine into a shareable image (see Section 3.4.1).
• Define the system logical name ACMSDI_GET_VERSION on the TP Desktop Connector Gateway for ACMS system to point to the ACMSDI_GET_VERSION shareable image file (see Section 3.4.2).
  If the logical name is not defined or the action routine cannot be located, the TP Desktop Connector Gateway for ACMS logs a message in the SWL and continues without calling the routine.

To create a shareable image that the TP Desktop Connector Gateway for ACMS calls for checking versions, follow these steps:

1. Edit according to the documented interface the sample file named ACMSDI_GET_VERSION.C in the ACMSDI$EXAMPLES directory. DIGITAL TP Desktop Connector for ACMS Client Services Reference Manual describes the interface.
2. Compile the routine:

   $ CC ACMSDI_GET_VERSION.C

   
   The next few steps make the routine available to the gateway.

3. Create a linker options file to make the routine externally visible.
   The file, for example, ACMSDI_GET_VERSION.OPT, must contain at least the following line:

   UNIVERSAL=ACMSDI_GET_VERSION

4. Link the ACMSDI_GET_VERSION routine into a shareable image using the compiled routine and the options file:

   $ LINK /SHAREABLE=ACMSDI_GET_VERSION.EXE - _$ ACMSDI_GET_VERSION.OBJ, ACMSDI_GET_VERSION.OPT/OPTIONS

   
   This creates the file ACMSDI_GET_VERSION.EXE in the current default directory.

5. Place the newly created shareable image in a secure directory.
   Because the gateway runs with elevated privileges, the ACMSDI_GET_VERSION routine runs with the same elevated privileges when that gateway calls it. Securing the image guards against a nonprivileged user gaining unauthorized privileges.

Section 3.4.2 tells how to point the gateway to the image file.

3.4.2 Defining the Version-Checking Logical Name

The gateway uses a logical name to access the ACMSDI_GET_VERSION routine as a shareable image (built as described in Section 3.4.1). Define the system logical name ACMSDI_GET_VERSION to translate to the device, directory, and file name of the image stored in the secure directory:

$ DEFINE /SYSTEM ACMSDI_GET_VERSION - _$ SECURE_DEVICE:[SECURE_DIRECTORY]ACMSDI_GET_VERSION

The gateway tries to find and invoke the ACMSDI_GET_VERSION routine only if a desktop client program signs in to the DIGITAL ACMS system and requests version checking by specifying it as a submitter option. After the gateway searches for the shareable image and routine the first time after its restart, the same image and routine are used until the gateway restarts again.