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: If you are new to programming with ACMS software, Compaq recommends reading the following books before using the TP Desktop Connector for ACMS product: For additional information on ACMS software, refer to the following manuals: For information on OpenVMS programming tools and Compaq software engineering standards and practices, refer to these documents:

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