Compaq TP Desktop Connector
for ACMS
Client Application Programming Guide


Previous Contents Index

2.4.3 Data Validation

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 ACMS system.

2.4.4 Data Integrity

Like ACMS software, TP Desktop software generally relies on the data management systems employed in the 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 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 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:

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

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

2.5 Design Conclusions

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 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.


Chapter 3
Developing Compaq ACMS Applications

This chapter presents guidelines for development work you do on the Compaq 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 ACMS applications access.
  2. Create definitions for the tasks in your 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 ACMS solutions that do not use TP Desktop Connector software.

Refer to the 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 ACMS solution can be reduced by having common data definitions in the ACMS application and in the desktop client program.

Note

The command procedure MAKE_RECORDS.COM found in the ACMSDI$EXAMPLES directory provides an example that automates creating common data definitions and converting data for the C and COBOL languages. You may need to edit the command procedure for the language you are using.

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 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 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 ACMS application starts.

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

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 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.

3.4 Enabling Version Checking on OpenVMS Systems

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:

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:

3.4.1 Building the ACMSDI_GET_VERSION Shareable Image

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


Previous Next Contents Index