# Compaq TP Desktop Connector
for ACMS
Client Application Programming Guide

Previous | Contents | Index

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

- 8-bit ASCII (no conversion needed)
- Long integer (byteswap)
- Short integer (byteswap)
- Quadword integer (byteswap)
- Date and time (primitives only)
- Counted string (byteswap count field)
- OpenVMS f-floating point (single precision)
- OpenVMS g-floating point (double precision)

The following data types are not converted:

- OpenVMS d-floating point
- OpenVMS h-floating point
- Segmented string (byteswap segment pointers and lengths)

### 8.1.8.2 MacToVms Function Description

MacToVms conversion routine converts data elements from Macintosh to OpenVMS format. This routine accepts a pointer to an existing Macintosh element and a pointer to a location where the element is placed after it is converted to OpenVMS format.

The pointers can be to the same location, causing a conversion in place. The MactoVMS routine also accepts a single char, indicating the data type and another short int indicating the length of the element. The length indicator is ignored except when the data type is text. It converts the element and places it where the user wants it.

The routine returns a short int with one of the following values:

- 0 = no error
- 4 = invalid data type

MacToVms Input Parameters

- Macintosh format element pointer (read only)
  Pointer to the Macintosh element to be converted to OpenVMS format.
- OpenVMS format element pointer (write only)
  Pointer to the location where the element is to be placed after it is converted to OpenVMS format.

- Data Type (read only)
  The data type of the element being converted. Table 8-2 lists the MacToVMS data types.

  Table 8-2 MacToVms Data Types
  Data Type | Code | Description
  --- | --- | ---
  Single byte | '1' | No conversion is performed.
  Short integer | '2' | Bytes 1 and 2 are swapped.
  Counted field | '3' | Short int count field preceding data is byteswapped; data is skipped.
  Long integer | '4' | Bytes 1 and 4 are swapped; bytes 2 and 3 are swapped.
  Text field | '5' | No conversion is performed.
  Date and time | '6' | Primitive conversions only. The long integer Macintosh time counter is converted to a quadword (C type comp) OpenVMS time counter.
  ... | '7' | Reserved.
  Quadword | '8' | Passed as a single 8-byte field. Bytes 8 and 1 are swapped, bytes 7 and 2 are swapped, bytes 6 and 3 are swapped, and bytes 5 and 4 are swapped.
  Float | 'F' | Single precision Macintosh floating-point number is converted to an OpenVMS type f single-precision, floating-point number.
  Double | 'D' | Double-precision Macintosh floating-point number is converted to an OpenVMS type g double-precision floating-point number.

  The include file acmsdi_mac.h contains symbols that you can use to represent the data type codes.
- Data length (read only)
  Applicable to type text only ('5' above), the length of the text field.

MacToVms Function Prototype

    pascal short MacToVms (void *MACFmt,
                           void *VMSFmt,
                           char dType,
                           unsigned short len);

This function prototype is included in file acmsdi_mac.h.

### 8.1.8.3 VmsToMac Function Description

The VmsToMac routine converts data elements from OpenVMS to Macintosh format. This routine accepts a pointer to an existing OpenVMS element and a pointer to a location where the element is placed after it is converted to Macintosh format.

The pointers can be to the same location, causing a conversion in place. Also accepts a single char, indicating the data type and another short int indicating the length of the element. The length indicator is ignored except when the data type is text. Converts the element and places it where the user wants it.

The routine returns a short int with one of the following values:

- 0 = no error
- 4 = invalid data type

VmsToMac Input Parameters

- OpenVMS format element pointer (read only)
  Pointer to the OpenVMS element to be converted to Macintosh format.
- Macintosh format element pointer (write only)
  Pointer to location where the element is to be placed after it is converted to Macintosh format.
- Data type (read only)
  The data type of the element being converted. Table 8-3 lists the VmsToMac data types.

  Table 8-3 VmsToMac Data Types
  Data Type | Code | Description
  --- | --- | ---
  Single byte | '1' | No conversion is performed.
  Short integer | '2' | Bytes 1 and 2 are swapped.
  Counted field | '3' | Short int count field preceding data is byteswapped; data is skipped.
  Long integer | '4' | Bytes 1 and 4 are swapped; bytes 2 and 3 are swapped.
  Text field | '5' | No conversion is performed.
  Date and time | '6' | Primitive conversions only. The quadword (C type comp) OpenVMS counter is converted to a long integer Macintosh time counter.
  ... | '7' | Reserved.
  Quadword | '8' | Passed as a single 8-byte field. Bytes 8 and 1 are swapped, bytes 7 and 2 are swapped, bytes 6 and 3 are swapped and bytes 5 and 4 are swapped.
  Float | 'F' | Single-precision OpenVMS floating-point number is converted to a Macintosh single-precision floating-point number.
  Double | 'D' | Double-precision OpenVMS type g floating-point number is converted to a Macintosh double-precision floating-point number.

  The include file acmsdi_mac.h contains symbols that you can use to represent the data-type codes.
- Data length (read only)
  Applicable to type text only ('5' above). The length of the text field.

VmsToMac Function Prototype

    pascal short VmsToMac (void *VMSFmt,
                           void *MACFmt,
                           char dType,
                           unsigned short len);

This function prototype is included in file acmsdi_mac.h.

### 8.1.8.4 Locating and Using the Data Type Conversion Module

The data type conversion module is in object form in the Utilities folder within the Acmsdi-System folder. Its name is dataConversions.c.o. A copy of the header file acmsdi_mac.h is also in the folder, to be used when compiling your application modules.

After writing an application module that includes either MacToVms, VmsToMac, or both function calls, you must link the module with three of the object files found in the utilities folder. These three files are dataConversions.c.o, DateConversion.c.o, and byteswap.c.o.

Look in the acmsdi_mac.h file in the Utilities folder with the Acmsdi_System folder for information on data conversion routines and macros.

## 8.1.9 Communication Tools Supported by TP Desktop Connector

TP Desktop Connector software supports five communication protocols between the Macintosh desktop client program and the TP Desktop Connector Gateway for ACMS:

- Direct DECnet communication
  Requires PATHWORKS for Macintosh Version 1.1 or higher software. Figure 8-2 shows this model for a TP Desktop Connector solution.

  Figure 8-2 Using the DECnet Tool on Macintosh

- AppleTalk-to-DECnet communication through an AppleTalk/DECnet Transport Gateway
  Requires PATHWORKS for Macintosh Version 1.0 software or higher.
  In a network that supports only AppleTalk between the Macintosh systems, an AppleTalk-DECnet Transport gateway allows a Macintosh desktop client program to communicate with an ACMS system through the DECnet transport. Figure 8-3 shows this model for a TP Desktop Connector solution.
- MacTCP Tool
  Requires PATHWORKS for Macintosh Version 1.1 or higher, which provides the MacTCP tool for communication through the TCP/IP transport.
- Direct AppleTalk communication
  Requires AppleTalk for OpenVMS Version 3.0 or higher on the host, and AppleTalk ADSP Tool on the Macintosh client. Provides a direct communication link to the host system using the AppleTalk Data Stream Protocol (ADSP) without the need for a gateway.
- Serial communication through the TP Desktop Connector Serial-DECnet gateway
  Requires the Calypso tool from Apple Computer (which allows you to specify the actual serial communications tool to user) and another serial communications tool such as the Serial Tool.
  Allows users who are not part of a network, or are at a remote location, to access ACMS applications over a serial line without the need to manage a network or purchase networking programs.

In Figure 8-3, the TP Desktop Connector gateway can reside on the same system as the AppleTalk-DECnet Transport gateway, although this is not a requirement.

Figure 8-3 Using the AppleTalk-DECnet Tool on Macintosh

## 8.1.10 Unidirectional Workspaces

A unidirectional workspace is a workspace that travels in one direction on TP Desktop Connector CallTask and EndTask requests. TP Desktop Connector provides three types of workspaces, two of which are unidirectional. The three types of workspaces are:

- Read-only (unidirectional)
  Sent from the Macintosh client to the TP Desktop Connector gateway on OpenVMS.
- Write-only (unidirectional)
  Sent from the TP Desktop Connector gateway to the Macintosh client.
- Modify (bidirectional)
  Sent from the Macintosh client to the TP Desktop Connector gateway on a CallTask request and sent back to the Macintosh client from the back-end gateway on a CallTask response.

Note The read and the write are from the perspective of the ACMS application (back-end) perspective.

The three arguments affected by unidirectional workspaces are flags, buffer, and length. You identify a read-only workspace to the DDEV with the flags parameter of the DBSendItem function. You also identify write-only workspaces with the flags parameter of the DBSendItem function. Because no actual data is sent with the write-only workspace, you can specify the DBSendItem buffer parameter as NULL. You do need to specify the length parameter of the write-only workspace, because the TP Desktop Connector gateway needs to know how long the workspace is to allocate a buffer for it on the host node.

If you use NULL for the flags parameter on the DBSendItem function, TP Desktop Connector defaults to a modify workspace. See Section 8.2.3.1 for information on specifying the parameters to the DBSendItem function.

## 8.1.11 Checking Software Versions

TP Desktop Connector DDEV does not provide a mechanism for comparing versions of ACMS software and desktop client programs. To protect against problems caused by version differences, include version information in a workspace sent on the CallTask request for comparison in a processing step in the ACMS application. If the processing step detects a difference in version, it can then terminate the task and return a message such as "incompatible versions" to the desktop client program.

# 8.2 Implementing Macintosh Desktop Client Programs

The work of implementing the desktop client program falls into the following major areas:

- Readying the Data Access Manager and performing other initialization work (see Section 8.2.1).
- Starting the session---getting information from the user and signing the user in to the ACMS system (see Section 8.2.2).
- Calling a task---accepting data from the user, preparing the data for transmission to the ACMS system, and calling an ACMS task (see Section 8.2.3).
- Receiving information from a task---checking for successful completion of the task, retrieving returned data, performing data conversions, and displaying that data to the user (see Section 8.2.4).
  The program can loop to repeat accepting data and checking completion.
- Ending an active session with the ACMS system (see Section 8.2.5).
- Getting error information (see Section 8.2.6).

Sections 8.4 and 8.5 describe how to build and debug the code you write. Compaq TP Desktop Connector for ACMS Client Services Reference Manual fully describes the TP Desktop Connector DAM services shown in the examples used in this section.

## 8.2.1 Readying the Data Access Manager

After your desktop client program completes initialization work, such as setting up fonts, windows, menus, and other tools, the program loads the Data Access Manager by calling InitDBPack, as shown in Example 8-1.

Example 8-1 Initializing the Data Access Manager

    short    status;    /* Status Variable */

        status = InitDBPack();
        if (status !=  noErr)
            {
            printf ("InitDBPack failed. Error code %d\n", status);
            exit (0);
            }

Any error in calling InitDBPack is unrecoverable. The interface routine that implements the InitDBPack function includes a version number for DAM. If the package version returned differs from that specified by the interface routine, the InitDBPack function returns the rcDBWrongVersion return status. If an error occurs in calling InitDBPack, the desktop client program should notify the user of the failure and then exit.

For the HyperCard implementation of AVERTZ, this initialization is handled in the main (stack) script that invokes the ACMSInitPack XFCN, as shown in Example 8-2.

Example 8-2 Calling ACMSInitPack

    on initCall    -- called from "on openstack"
       .
       .
       .
            put ACMSInitPack() into lastStatus
            if laststatus is not 0 then
                    answer "Initialization error"
            end if
    end initCall

## 8.2.2 Starting a Session

After the Data Access Manager is loaded, the desktop client program can start sessions with an ACMS system. To start a session, use the DBInit service as shown in Example 8-3.

Example 8-3 Calling DBInit

    short       status;                                 /* Status Variable */
    long        sessid1;                                /* Session Id      */
    char        username[255];                          /* Username Name */
    char        password[255];                          /* Password */
    #define ddev       "\pACMSDI"                       /* ACMSDI DDEV */
    #define node       "\pBOSTON"                       /* Node Name */
    #define connstring "\p\"Appletalk-DECnet Tool\"TimeOut 30"/* Communication String */
        status = get_access( &username, &password );    /* get username and password */
        if (status != noErr)
                my_exit (status, 0, "Could not get username and password");

        status = DBInit (&sessid1,
                          ddev,
                          node,
                          username,
                          password,
                          connstring,
                          NULL );

        if (status != noErr)
             my_exit (status, sessid1, "DBInit Failed");

The DBInit service executes synchronously in block mode, stalling the program until the ACMS system processes the sign-in request. However, if you include a TimeOut argument as shown in Example 8-3, you can limit the time the DDEV waits for a connection to occur. Example 8-3 specifies 30 seconds. If you do not specify a TimeOut argument, the default wait time is 60 seconds.

You include special sign-in parameters for the TP Desktop Connector DAM API in the connection string argument passed to the DDEV with the DBInit calls. The connection string is a Pascal-type string containing parameters that specify sign-in options.

To enable a communications tool on a desktop system configured with the appropriate software, specify one of the following Pascal-formatted text strings in the connection string parameter:

    "\p\"DECnet Tool\"" for DECnet software
    "\p\"AppleTalk-DECnet Tool\"" for AppleTalk-DECnet Transport Gateway
    software
    "\p\"MacTCP Tool\"" for TCP/IP Transport Services
    "\p\"AppleTalk ADSP Tool\""for direct AppleTalk (with no gateway)
    "\p\"XPC Tool\"" for serial communication services

You can also use the connection string to specify additional arguments to control the communications connection. Most of the connection string arguments are directly related to the communications tool specified. However, you can use the following arguments with all communications tools:

- TimeOut
  Specifies the length of time that the DDEV attempts to establish a communications connection.
- IntegrityCheck
  Activates cyclic redundancy checking (CRC) from the Macintosh client application. See Compaq TP Desktop Connector for ACMS Gateway Management Guide for information on CRC.
- BufferSize
  Specifies the size of the message buffers the DDEV uses to transfer data to and from the communications tool.

For more information on these special arguments to the connection string argument, see Compaq TP Desktop for ACMS Gateway Management Guide.

If the ACMS sign-in succeeds, the status noErr is returned and a nonzero session identification is returned in the sessid parameter. This session identification is unique on the desktop system (not on the network) and is used on all other calls to the TP Desktop Connector DDEV for the session.

If the DBInit call or the sign-in request fails, a status other than noErr and a nonzero session identification are normally returned. This nonzero session identification refers to what is called a zombie session, which is a session that does not have a network connection and is, therefore, useful only to check error conditions on the DBInit call. The desktop client program can call DBGetErr to receive more information about the error condition. The desktop client program must call DBEnd to close the session and free up session resources (see Section 8.2.5). The error codes returned by the DBInit service are listed in Compaq TP Desktop Connector for ACMS Client Services Reference Manual.

If the status rcDBError is returned, errors are usually related to the following types of problems:

- Requested node is not available on the network.
- Maximum number of active sessions is exceeded on the Macintosh.
- User authorization failed.

The TP Desktop Connector client services allow the desktop client program to create as many sessions as resources permit, to a maximum of 32. Each session can have only one task active at any time. If the user activity requires data from several tasks at the same time, the desktop client program can start multiple sign-ins. These sign-ins can be with a single ACMS system, different nodes within a single VMScluster, nodes that are not in the same VMScluster, or any combination of the three connections. For more information on failover and connectivity, see Section 2.2.6 and Section 2.3.

The HyperCard implementation of AVERTZ calls the DBInit function as part of the ACMSLogon XFCN. ACMSLogon is called in the Message Catcher script, as shown in Example 8-4.

Example 8-4 Calling ACMSLogon

    function createSession
       .
       .
       .
        put ACMSLogon ("newSid","ACMSDI",nodeHold,userID,PWhold,connstr) into laststatus
        if laststatus is not 0 then
            put GetErr (newSid,"ACMS End On Failed Login") into stat
            put ACMSEnd (newSID) into stat
        end if
       .
       .
       .
    end createSession

Previous | Next | Contents | Index