| Previous | Contents | Index |
This chapter describes how to develop Macintosh desktop client programs using DIGITALTP Desktop Connector software.
For information on configuring network transports, see DIGITAL 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, Digital supplies the TP Desktop Connector DDEV.
8.1.2 Desktop Client Program Processing Flow
Your desktop client program is responsible for the following activities:
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:
To build this interaction between a Macintosh program and an ACMS system, use these services:
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:
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.
| 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 |
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. Digital recommends that this conversion be done in the Macintosh desktop client program.
The DDEV provides the following benefits:
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 DIGITAL 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 DIGITAL 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:
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:
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); |
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.
8.1.8.1 Data Conversion Module Description
The data conversion module converts a data element of a given data type from Macintosh to OpenVMS format and OpenVMS to Macintosh format.
The following data types are converted:
The following data types are not converted:
| Previous | Next | Contents | Index |