# Compaq TP Desktop Connector
for ACMS

# Client Services Reference Manual

Order Number: AA--PVNFF--TE

# August 1999

This manual describes the services and commands needed to create and maintain TP Desktop Connector client programs that use the portable API.
Revision Update Information: This is a revised manual.
Operating System: Compaq OpenVMS VAX
Compaq OpenVMS Alpha
Software Version: Compaq TP Desktop Connector
Version 3.1A for ACMS
Compaq Computer Corporation
Houston, Texas

August 1999

COMPAQ COMPUTER CORPORATION SHALL NOT BE LIABLE FOR TECHNICAL OR EDITORIAL ERRORS OR OMISSIONS CONTAINED HEREIN, NOR FOR INCIDENTAL OR CONSEQUENTIAL DAMAGES RESULTING FROM THE FURNISHINGS, PERFORMANCE, OR USE OF THIS MATERIAL. THIS INFORMATION IS PROVIDED "AS IS" AND COMPAQ COMPUTER CORPORATION DISCLAIMS ANY WARRANTIES, EXPRESS, IMPLIED, OR STATUTORY, AND EXPRESSLY DISCLAIMS THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR PARTICULAR PURPOSE, GOOD TITLE, AND AGAINST INFRINGEMENT.

#### © 1993--1999 Digital Equipment Corporation. All Rights Reserved.

This publication contains information protected by copyright. No part of this publication may be photocopied or reproduced in any form without prior written consent from Compaq Computer Corporation.

The software described in this manual is furnished under a license agreement or nondisclosure agreement. The software may be used or copied only in accordance with the terms of the agreement.

Compaq and the Compaq logo are registered in the United States Patent and Trademark Office. Printed in U.S.A.

ACMS, DEC, DECdesign, DECforms, DECnet, DECnet-DOS, DECtp, DECwindows, OpenVMS, PATHWORKS, PATHWORKS for DOS, PATHWORKS for Macintosh, TP Desktop Connector, VAX, VAXcluster, VAXset, VMS, VT, and the DIGITAL logo are trademarks of Compaq Computer Corporation..)

The following are third-party trademarks:

Apple, AppleTalk, HyperCard, HyperTalk, Macintosh, and MacTCP are registered trademarks of Apple Computer, Inc.

DECnet/IPX Portal, InterConnections, Inc., Network Print Services, NPS, Terminal Emulation Services, and TES are trademarks of InterConnections, Inc.

4D, 4D External Kit, and 4th Dimension 4D are registered trademarks or trademarks of ACI and ACIUS, Inc.

Microsoft, Microsoft C, Microsoft COBOL, Microsoft Windows, Microsoft Windows 95, MS, MS-DOS, and Visual Basic are registered trademarks of Microsoft Corporation. Windows NT is a trademark of Microsoft Corporation.

Motif and OSF/Motif are registered trademarks of the Open Software Foundation, Inc.

NetWare and Novell are registered trademarks of Novell, Inc.

Open Desktop and SCO are trademarks of Santa Cruz Operations, Inc.

Open Look is a registered trademark of UNIX System Laboratories, Inc., a wholly owned subsidiary of Novell, Inc.

Oracle CDD and Oracle Rdb are registered trademarks of Oracle Corporation.

UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company, Ltd.

X Window System is a registered trademark of Massachusetts Institute of Technology.

All other trademarks and registered trademarks are the property of their respective holders.

This document is available on CDROM.

This document was prepared using VAX DOCUMENT, Version V3.2-1n.

Contents | Index

# Preface

This manual provides reference information for the Compaq TP Desktop Connector client services, formerly known as the ACMS Desktop Portable API.

# Intended Audience

This guide is intended for application programmers, application designers, and system managers.

# Manual Structure

This manual has the following structure:

Chapter | Description
--- | ---
Chapter 1 | Explains the format of the reference information.
Chapters 2, 3, 4, 5, and 6 | Contain the reference information on Compaq TP Desktop Connector client services, presentation procedures, action routines, and the Compaq OpenVMS based system management service.
Chapter 7 | Lists the serial communications commands.
Chapter 8 | Lists the data compression monitor commands.
Appendix A | Lists the Compaq ACMS system status values that can be returned in the err2 parameter.

# Related Documents

For information on developing Compaq ACMS applications, refer to the following manuals:

- Compaq TP Desktop Connector for ACMS Client Application Programming Guide
Provides information for designing, coding, and implementing a TP Desktop Connector solution.
- Compaq TP Desktop Connector for ACMS Installation Guide
Provides the steps needed to install a TP Desktop Connector gateway on an OpenVMS system and the TP Desktop Connector software on the desktop client system.
- Compaq TP Desktop Connector for ACMS Gateway Management Guide
Contains information about the system management and administration of the TP Desktop Connector gateway. It also includes information on the methodology of the use of network transports.
- Compaq TP Desktop Connector for ACMS Getting Started
Provides a high-level discussion and examples of the activities to develop, install, and run a complete application.
- Compaq TP Desktop Connector 4D Externals User's Guide --- online only
Describes a set of 4D external functions you can use to create a TP Desktop Connector client program using 4th Dimension as a development platform. Look for this book on your Macintosh in the acmsdi-examples folder.

If you are new to programming with ACMS software, Compaq recommends reading the following books before using the TP Desktop Connector for ACMS product:

- Compaq ACMS for OpenVMS Writing Applications
Describes procedures to follow using the Application Development Utility (ADU).
- Compaq ACMS for OpenVMS Writing Server Procedures
Describes how to write and debug procedures for ACMS applications. Also supplies reference information for application and system programming services.

For additional information on ACMS software, refer to the following manuals:

- Compaq ACMS for OpenVMS Introduction
Describes basic concepts and terms concerning the ACMS environment.
- Compaq ACMS for OpenVMS ADU Reference Manual
Describes the details of the syntax for the definitions you create and the commands you use to build the run-time components.
- DECtp Implementation Toolkit
Provides valuable extensions to DECSet tools to tailor them for developing an Compaq ACMS solution. Available through Compaq Services.
- DECtp Design Toolkit
Provides valuable extensions to DECdesign software to help design effective ACMS solutions. Available through Compaq Services.

For information on OpenVMS programming tools and Compaq software engineering standards and practices, refer to these documents:

- Using DECset
Describes the OpenVMS programming environment, provides helpful hints about conducting a software project, and shows a case study of DECset tools. Provided with the DECset documentation set.
The Compaq ACMS documentation also describes how you can use the DECset tools to create an effective development environment.
- The Digital Guide to Software Development
Describes the DIGITAL incremental approach to software development and outlines standards applied in software development. Published by DIGITAL Press and written for managers, programmers, and documentation writers.

# Conventions

This guide uses the following conventions and symbols:

TP Desktop Connector | Refers to the Compaq TP Desktop Connector for ACMS software.
`User Input` | In examples, user input is highlighted with bold type.
`$` | The dollar sign indicates a generic command line prompt. This prompt may be different on your system.
`[Return]` | A key name in a box indicates that you press that key on the keyboard.
`[Ctrl/x]` | Press the Ctrl (control) key and hold it down while pressing the specified key (indicated here by x).
WORD | Uppercase text indicates OpenVMS data types, commands, keywords, logical names, and routines or services; C files and data structures; Microsoft Windows data structures; or HyperCard data types.
word | In format descriptions, lowercase words indicate parameters, variables, services, or procedures.
italics | Italics are used for emphasis and for parameters in text. Titles of manuals are also italicized.
[] | In format descriptions, square brackets surround a choice of options; select none, one, several, or all of the choices.
. . . | A vertical ellipsis in an example means that information not directly related to the example has been omitted.

# Chapter 1
Service Format

This chapter describes the format and elements of the service descriptions provided in following chapters. This chapter also provides a list of the services and the appropriate session environments in which each service may be used.

# 1.1 Routine Names

The TP Desktop Connector service names and OpenVMS action routines are shown in C-language format. The OpenVMS system management services are shown in the OpenVMS services format.

# 1.2 Format

The format section describes the C functions as they are declared for the portable API in the include file ACMSDI.H in the ACMSDI$COMMON directory and for Macintosh in the include file DatabaseAccess.h.

Square brackets ([]) indicate optional parameters in the call.

# 1.3 Parameters

This section contains details about each parameter listed in the format section. Parameters appear in the order in which they are shown in the format. The format shown in Table 1-1 describes each parameter.

Table 1-1 Services Description Parameters
Name | Description
--- | ---
Type | Data type of the parameter
Access | Method by which the called routine accesses the parameter
Mechanism | Method by which a parameter is passed to the called routine

The parameters section additionally contains a sentence or two describing the purpose of the parameter.

## 1.3.1 Type Entry

Table 1-2 lists the C-language data types used in the TP Desktop Connector services.

Table 1-2 Parameter Data Types
Data Type | Description
--- | ---
ACMSDI_CALL_ID | Identification returned by the acmsdi_call_task service
ACMSDI_FORM_RECORD | Structure defined in the ACMSDI.H include file (see Section 3.1.2)
ACMSDI_FORM_RECORD_BIND | Structure defined in the ACMSDI.H and ACMSDI.BAS include files (see Section 4.1.1)
ACMSDI_FORMS_SESSION_ID | Structure defined in the ACMSDI.H include file (see Section 3.5)
ACMSDI_OPTION | Union to specify sign-in options (see Section 2.11)
ACMSDI_CALL_OPTIONS | Union to specify call task options
ACMSDI_SUBMITTER_ID | Structure defined in the ACMSDI.H include file (see Section 2.11)
ACMSDI_WORKSPACE | Array of structures defined in the ACMSDI.H include file to pass workspaces between the desktop system and the TP Desktop Connector gateway (see Section 2.4)
ACMSDI_WORKSPACE_BIND | Structure defined in the ACMSDI.H and ACMSDI.BAS include files (see Section 4.1.2)
ACMSDI_WORKSPACE_OPT | Array of structures defined in the ACMSDI.H include file to pass unidirectional workspaces between the desktop system and the TP Desktop Connector server
char * | Array of unsigned 8-bit integers
character string descriptor | Address of an OpenVMS string descriptor pointing to the character string to be passed
function address | Address of a function that complies with the prototype in ACMSDI.H for the completion routine
int | 16-bit signed integer on DOS and SCO UNIX systems, 32-bit signed integer on OpenVMS and Compaq Tru64 UNIX systems
long | Synonym for long int
long int | 32-bit signed integer
longword | 32-bit unsigned integer
ptr | Longword pointer to data buffer
short | Synonym for short int
short int | 16-bit signed integer
unsigned long int | 32-bit unsigned integer
void * | Pointer to object of unknown type

## 1.3.2 Access

Access describes the way in which the called routine accesses the data specified by the parameter. The access methods are described in Table 1-3.

Table 1-3 Called Routine Access Methods
Access Method | Description
--- | ---
Read | Data needed by the called routine to perform its operation is read but not returned.
Write | Data that the called routine returns to the calling routine is written into a location accessible to the calling routine.
Modify | Data is both read and returned by the called routine; input data specified by the parameter is overwritten.

## 1.3.3 Mechanism

The parameter-passing mechanism is the way in which a parameter specifies the data to be used by the called routine. The passing mechanisms are described in Table 1-4.

Table 1-4 Parameter-Passing Mechanisms
Mechanism | Description
--- | ---
By value | The parameter contains a copy of the data to be used by the routine.
By reference | The parameter contains the address of the data to be used by the routine. The parameter is a pointer to the data. Because C supports only call by value, write parameters other than arrays and structures must be passed as pointers. References to names of arrays and structures are converted by the compiler to pointer expressions.

For information on whether the caller or the called routine allocates memory, see the discussions of the individual platforms.

# 1.4 Return Status

Each service returns a status value defined as follows:

Platform | Value
--- | ---
DOS/Windows | long int
Windows 95 | long int
Macintosh | short int
OpenVMS | long int
Compaq Tru64 UNIX | long int
SCO UNIX | long int

Only the status codes defined in the related reference sections are valid in the TP Desktop Connector client services. The definitions for the return status values are in include files as follows:

Type of Services | Include File
--- | ---
Portable client services | ACMSDI$COMMON:ACMSDI.H
Client services for Macintosh software | ACMSDI_MAC.H

# 1.5 Session Environments

Client services can be used in three different session environments, blocking, nonblocking, and forced nonblocking. In a blocking environment, service routines are completed in one procedure. In a nonblocking environment, service routines return control to the desktop client program as soon as a request is sent and then call the appropriate completion routine when the request is completed or call the appropriate presentation procedure when an exchange step is detected.

In a forced nonblocking environment, service routines provide a method of polling that is used to determine the type of message sent from the back-end server. This message type may then be used to determine the appropriate action (for example, process the call completion or exchange step). The forced nonblocking software provides additional routines to access call completion and exchange step arguments. These session environments are explained in more depth in Chapter 2 and in Compaq TP Desktop Connector for ACMS Client Application Programming Guide.

Table 1-5 lists the services and indicates the session environments in which you can use each call.

Table 1-5 Matrix of Services and Environments
Service | Availability within Environment
--- | ---
| Blocking | Nonblocking | Forced Nonblocking
acmsdi_call_task See description in Section 2.6 | yes | yes | yes
acmsdi_cancel See description in Section 2.7 | - | yes | yes
acmsdi_complete_pp See description in Section 2.8 | - | yes | yes
acmsdi_dispatch_message See description in Section 2.9 | - | yes | -
acmsdi_return_pointer See description in Section 2.10 | yes | - | yes
acmsdi_sign_in See description in Section 2.11 | yes | yes | yes
acmsdi_sign_out See description in Section 2.12 | yes | yes | yes
acmsdi_poll See description in Section 4.13 | - | - | yes
acmsdi_complete_call See description in Section 4.2 | - | - | yes
acmsdi_bind_enable_args See description in Section 4.3 | - | - | yes
acmsdi_bind_send_args See description in Section 4.9 | - | - | yes
acmsdi_bind_receive_args See description in Section 4.5 | - | - | yes
acmsdi_bind_transceive_args See description in Section 4.12 | - | - | yes
acmsdi_bind_msg See description in Section 4.4 | - | - | yes
acmsdi_bind_request_args See description in Section 4.7 | - | - | yes
acmsdi_bind_session_id See description in Section 4.11 | - | - | yes
acmsdi_bind_send_recs See description in Section 4.10 | - | - | yes
acmsdi_bind_receive_recs See description in Section 4.6 | - | - | yes
acmsdi_bind_request_wksps See description in Section 4.8 | - | - | yes
Callbacks
acmsdi_disable See description in Section 3.4 | - | yes | -
acmsdi_enable See description in Section 3.5 | - | yes | -
acmsdi_read_msg See description in Section 3.6 | - | yes | -
acmsdi_receive See description in Section 3.7 | - | yes | -
acmsdi_request See description in Section 3.8 | - | yes | -
acmsdi_send See description in Section 3.9 | - | yes | -
acmsdi_transceive See description in Section 3.10 | - | yes | -
acmsdi_write_msg See description in Section 3.11 | - | yes | -
acmsdi_check_version See description in Section 3.12.1 | - | yes | -
acmsdi_get_version(back end) See description in Section 3.12.2 | - | yes | yes

Next | Contents | Index