# Compaq TP Desktop Connector
for ACMS
Client Application Programming Guide

Previous | Contents | Index

# Chapter 8
Developing Macintosh Desktop Client Programs

This chapter describes how to develop Macintosh desktop client programs using Compaq TP Desktop Connector software.

For information on configuring network transports, see Compaq TP Desktop Connector for ACMS Gateway Management Guide.

# 8.1 Guidelines for Developing Macintosh Desktop Client Programs

TP Desktop Connector software allows you to run ACMS tasks from desktop client programs running on Macintosh desktop systems. Unlike the programming interface for DOS desktop systems, however, the programming interface for Macintosh desktop systems is not based on the ACMS Systems Interface (SI). Instead, it is based on a native Macintosh interface, the Data Access Manager (DAM) services. The following sections introduce this interface and the way to use it with TP Desktop Connector software.

## 8.1.1 Data Access Manager

DAM is a common set of services that provides communication between an application running on the Macintosh and other systems. Running on the Macintosh desktop system, the desktop client program defines what back-end system it wants to communicate with and which Database Extension DDEV to use for that communication. For TP Desktop Connector applications, Compaq supplies the TP Desktop Connector DDEV.

## 8.1.2 Desktop Client Program Processing Flow

Your desktop client program is responsible for the following activities:

- Preparing a request (or query) to be sent to the ACMS system
- Retrieving the response to the request
- Performing any data conversion or translation required

Figure 8-1 and the annotations show the interaction between the desktop client program and the ACMS system with the low-level DAM interface provided by TP Desktop Connector.

Figure 8-1 Data Access Manager and ACMS System Interaction

Figure 8-1 shows the following activities:

1. User asks to retrieve customer information.
2. Desktop client program uses DAM services to send a request to the TP Desktop Connector Gateway for ACMS.
3. DDEV sends the request to the gateway.
4. The gateway invokes ACMS software to process the request.
5. ACMS system returns data to the gateway.
6. The gateway returns the data to the DDEV.
7. Desktop client program uses DAM services to check the DDEV for the returned data.
8. DDEV returns the requested data to the desktop client program.
9. Desktop client program displays the data to the user.

## 8.1.3 TP Desktop Connector Services for Macintosh

To build this interaction between a Macintosh program and an ACMS system, use these services:

- InitDBPack initializes the DAM software.
- DBInit loads the TP Desktop Connector DDEV, if necessary, and signs the user in to the ACMS system.
- DBGetConnInfo returns information about a given session, including the node with which the session is communicating, the current state of the connection, and so on.
- DBGetSessionNum returns the session number for a given session, where session 1 is the oldest currently active session, 2 is the next oldest currently active session and so on.
- DBSend and DBSendItem pass the individual elements of an ACMS request from the desktop client program to the TP Desktop Connector DDEV, which concatenates the elements into a single message. DBSendItem supports some special flags and data types that DBSend does not support, such as unidirectional workspaces. DBSend can pass only modify (bidirectional) workspaces.
- DBExec instructs the TP Desktop Connector DDEV to send the constructed message to the ACMS system.
- DBState checks whether the TP Desktop Connector DDEV received a response from the ACMS system.
- DBGetItem retrieves the response data from the TP Desktop Connector DDEV.
- DBGetErr retrieves status and error information from the ACMS DDEV.
- DBEnd signs the user out of the ACMS system.
- DBBreak cancels a currently executing task.

## 8.1.4 Restrictions

DAM supports two levels of interface: low-level and high-level. However, only the low-level interface is supported by TP Desktop Connector software. The low-level interface allows you to invoke functions on another system while retaining maximum control over the communications and data. Not available in TP Desktop Connector, the high-level interface provides a simpler programming interface for this interaction.

TP Desktop Connector does not support the following services:

- DBKill
- DBUnGetItem

As provided in other DDEV implementations, these DAM services allow the desktop client program to interrupt a DAM service, stop a DAM session and so on. A desktop client program written using the TP Desktop Connector version of the DAM services can still allow the user to exit from an activity without waiting for an ACMS task to complete. However, if you want to allow the desktop client program to end a session while a task is outstanding for that session, use the Communications Toolbox services to end the link, and DBEnd to clean up the session.

Some DDEVs provide both synchronous and asynchronous DAM services. The TP Desktop Connector DDEV supports only synchronous access to the TP Desktop Connector DAM services. Thus, when using the TP Desktop Connector DAM services, supply a NULL as the last argument for each TP Desktop Connector DAM service call, which is normally used for the AsyncParamBlk pointer.

The TP Desktop Connector DAM services support exchange steps. See Section 8.3 for information on using exchange steps.

## 8.1.5 Data Conversion and Data Types

Oracle CDD holds the definitions of data structures for ACMS workspaces, the components used to exchange information with an ACMS application. Table 8-1 lists the Macintosh data types and indicates whether they are supported by Oracle CDD software.

Table 8-1 Macintosh and Oracle CDD Data Types
Macintosh Data Type | Include File Constant 1 | Oracle CDD Data Type
--- | --- | ---
Any type | typeAnyType | None
Boolean | typeBoolean | None
Character | typeChar | TEXT
Column break | typeColBreak | None
Date 2 | typeDate | None
Date and time | typeTimeStamp | DATE
Decimal number | typeDecimal | PACKED DECIMAL
Discard next data item | typeDiscard | None
Floating-point | typeFloat | D_FLOATING
Integer | typeInteger | SIGNED LONGWORD
Long binary 3 | typeLBin | None
Long character 3 | typeLChar | None
Money value | typeMoney | None
No more data expected | typeNone | None
Row break | typeRowBreak | none
Short floating-point | typeSMFloat | F_FLOATING
Short integer | typeSMInt | SIGNED WORD
Time 2 | typeTime | None
Unknown | typeUnKnown | none
Variable binary 3 | typeVBin | None
Variable character | typeVChar | VARYING STRING

1The type definitions are in DatabaseAccess.h and Types.h.
2The corresponding Oracle CDD data type is both date and time.
3This data type is undefined but currently reserved on the Macintosh system.

The DDEV for TP Desktop Connector does not support automatic data conversion between Macintosh and OpenVMS data types. Either the desktop client program or the ACMS application must understand the format of the data being exchanged and convert it appropriately. Compaq recommends that this conversion be done in the Macintosh desktop client program.

The DDEV provides the following benefits:

- Supports greater transparency of the ACMS application
- Takes advantage of the processing power available on the Macintosh desktop system
- Provides a simpler migration, if and when data conversion is provided by the DDEV

The TP Desktop Connector DDEV uses the datatype parameter on the DBSendItem and DBGetItem services for special purposes related to header data items. See Section 8.3 for details. The DDEV ignores the datatype field for workspace data and assumes typeChar.

Before building a message to send to an ACMS task, the desktop client program must convert the data, so that the data is in the appropriate format for the workspace in which it is received in the ACMS application. For example, if the task contains a workspace with both a 200-byte character field and a 4-byte long-integer field, the desktop client program converts the long-integer field before it builds the message. When data is returned from the ACMS application, the desktop client program converts it to Macintosh format.

Character fields do not require conversion. If a task contains one workspace with a single 200-byte character field, the desktop client program must not convert the data for that field.

The desktop client program must understand the format of the data needed by the ACMS task. In the ACMS system, data formats are captured in the workspace definitions stored in the Oracle CDD dictionary. Section 3.2 outlines a procedure for generating a corresponding record definition that can be included in your desktop client program. For desktop data types that do not correspond precisely to OpenVMS data types, you can also create a table of fields and corresponding data types. Then use this table to call appropriate data conversion routines for each field.

TP Desktop Connector supplies routines to assist with data conversion. A conversion routine called _ByteSwap is provided for integer data types. Include this routine in your desktop client program to help with data conversion. See Section 8.1.6 for information on the _ByteSwap routine. In addition, VmsToMac and MacToVms routines are included for other data types.

TP Desktop Connector provides routines and macros to convert Macintosh to OpenVMS and OpenVMS to Macintosh date and time fields. See Section 8.1.7 for information on date and time conversion routines.

## 8.1.6 Routine for Data Conversion, _ByteSwap

Your program must properly convert the data fields in workspaces. The most common conversion required is for short- and long-integer fields. A routine, _ByteSwap, is provided with the TP Desktop Connector samples for Macintosh to assist you in converting data. This routine can also be called as part of the Macintosh data-type conversion package described in Section 8.1.8.

Among several differences in data types between Compaq VAX computers and Macintosh computers is the placement of high-order and low-order bytes in integer-type fields. For example, on the Macintosh, a long integer with a value of 100 000 is a 4-byte field with each byte represented by two hexadecimal digits:

    00 01 86 A0

On a VAX, the long integer 100 000 is represented as follows:

    A0 86 01 00

The first and fourth bytes and the second and third bytes are swapped.

Short integers are similar. For example, a short integer 1000 on the Macintosh is represented as a 2-byte field:

    03 E8

On the VAX, the short integer 1000 is represented as follows:

    E8 03

The two bytes are swapped.

The _ByteSwap routine performs the following functions:

- Converts a series of adjacent fields with one call
- Converts all fields identified as integer-type fields by swapping their bytes appropriately
- Converts a short integer count field representing the length of a subsequent text field and skips the following text field to look for the next field
- Bypasses any identified text field

The _ByteSwap prototype is as follows:

`_ByteSwap (char *buffer, char *string);`

where:

buffer | A pointer to the buffer containing the fields to be converted
string | A pointer to the data-type string, a NULL-terminated (C-type) string consisting of bytes representing the data types of the fields in the buffer, 1 byte for each field

The bytes in the data-type string to which the second parameter points are defined as follows:

Value | Meaning
--- | ---
'1' | A single-character field
'2' | A short integer field
'A' | An aligned short integer. Same as '2' except that the field is assumed to be aligned on a short integer boundary, and the buffer pointer is adjusted as needed
'3' | A counted text field preceded by a short integer containing the field length, where the short integer is initially in Macintosh format
'B' | An aligned counted text field. Same as '3' except that the field is assumed to be aligned on a short integer boundary, and the buffer pointer is adjusted as needed
'4' | A long integer
'D' | An aligned long integer. Same as '4' except that the field is assumed to be aligned on a long integer boundary and the buffer pointer is adjusted as needed
'5x' | A text field, where x is a single byte containing the length of the field (1 to 255)
'6' | A counted text field preceded by a short integer containing the field length, where the short integer is initially in OpenVMS format
'C' | An aligned counted text field. Same as '6' except that the field is assumed to be aligned on a short integer boundary, and the buffer pointer is adjusted as needed
'8' | A 64-bit integer
'E' | An aligned 64-bit integer. Same as '8' except that the field is assumed to be aligned on a 64-bit boundary, and the buffer pointer is adjusted as needed
'\0' | A null terminator indicating the end of the string

For example:

    _ByteSwap (buff, "2");

A single short integer is converted from VAX to Macintosh or from Macintosh to VAX, depending on its initial state:

    _ByteSwap (record, "11122425\007443");

The buffer to which record points contains the following fields:

- A text field with a length of 3 or 3 single-byte fields
- Two short integers
- A long integer
- A short integer
- A text field with a length of 7
- Two long integers
- A text field the length of which is contained in a preceding short integer

Depending on the initial state of the buffer, all fields are appropriately converted from VAX to Macintosh or from Macintosh to VAX. The _ByteSwap routine returns an integer containing the length of the buffer processed; the number of bytes swapped plus the number of bytes skipped.

The _ByteSwap routine is written in MPW C. Both the source and an object file are provided. Link the object file with your application.

## 8.1.7 Date Format Conversion Routines

Two routines called MACToVMSTime and VMSToMACTime are provided with the Macintosh sample for converting the date format between the Macintosh and OpenVMS formats. The source code for these routines is found in the DateConversion.C file in the utilities folder of the Acmsdi-Examples folder. These routines can also be called as part of the Macintosh data-type conversion package described in Section 8.1.8. In addition, the C language macro versions of these routines are located in the acmsdi_mac.h file.

### 8.1.7.1 MACToVMSTime

The MACToVMSTime routine converts Macintosh date and time in seconds since January 01, 1904 (unsigned longword integer) to OpenVMS date and time format ('quadword' on OpenVMS and 'comp' type on Macintosh systems). For example:

    comp MACToVMSTime (unsigned long);
       .
       .
       .
    main ()
    {
            comp vmstime;
            unsigned long mactime;
       .
       .
       .
            /* convert Macintosh format to OpenVMS format */

            vmstime = MACToVMSTime (mactime);
       .
       .
       .
            /* Remember to byteswap the comp 'vmstime'
               before sending it to the OpenVMS system */
       .
       .
       .
    }

The macro version of this routine is named MAC_TO_VMS_TIME. The macro performs the required byte-swapping in addition to the arithmetic conversion. The macro is written as follows:

    MAC_TO_VMS_TIME (vmstime, mactime);

### 8.1.7.2 VMSToMACTime

The VMSToMACTime routine converts OpenVMS date and time ('quadword' on OpenVMS and 'comp' type on Macintosh systems) to Macintosh date and time (unsigned longword, seconds since Jan 01, 1904). For example:

    unsigned long VMSToMACTime (comp);
       .
       .
       .
    main ()
    {
            comp vmstime;
            unsigned long mactime;
       .
       .
       .
            /* Remember to byteswap the quadword 'mactime'
               after receiving it from the OpenVMS system and
               before converting the format */
       .
       .
       .
            /* convert OpenVMS format to Mac format */

            mactime = VMSToMACTime (vmstime);
       .
       .
       .
    }

The macro version of this routine is named VMS_TO_MAC_TIME. The macro performs the required byte-swapping in addition to the arithmetic conversion. The macro is written as follows:

    VMS_TO_MAC_TIME (mactime,vmstime);

You can find these routines in the object form in the Utilities folder within the Acmsdi-System folder. HyperCard scripts cannot make calls to these routines directly, but a data type of 'tims' specified while using the ACMSGetWorkspace, ACMSGetResWorkspace, ACMSSendWorkspace, and ACMSSendResWorkspace XFCNs can be used to specify primitive date/time fields in a workspace. The XFCNs will perform the required conversions.

## 8.1.8 Macintosh Data Type Conversion Package

TP Desktop Connector provides a data conversion package for the Macintosh. This package allows you to convert most of the Macintosh data types to their corresponding OpenVMS data types and vice-versa.

Two functions are provided to perform data conversions: MacToVms to convert the data type of a Macintosh data element to its OpenVMS equivalent, and the VmsToMac to convert the data type of an OpenVMS data element to its Macintosh equivalent.

Previous | Next | Contents | Index