Order Number: AA--PVNFE--TE

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: DIGITAL OpenVMS VAX
DIGITAL OpenVMS Alpha

Software Version: DIGITAL TP Desktop Connector
Version 3.1 for ACMS

Compaq Computer Corporation
Houston, Texas

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.

Copyright © Digital Equipment Corporation 1993--1995, 1997, 1998, 1999

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 :CD-ROM.

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

Contents

Index

This manual provides reference information for the TP Desktop Connector for ACMS 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 DIGITAL TP Desktop Connector client services, presentation procedures, action routines, and the DIGITAL OpenVMS-based system management service.
Chapter 7	Lists the serial communications commands.
Chapter 8	Lists the data compression monitor commands.
Appendix A	Lists the DIGITAL ACMS system status values that can be returned in the err2 parameter.

Related Documents

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

• DIGITAL TP Desktop Connector for ACMS Client Application Programming Guide
  Provides information for designing, coding, and implementing a TP Desktop Connector solution.
• DIGITAL TP Desktop Connector for ACMS Installation Guide
  Provides the steps needed to install a TP Desktop Connector gateway on a OpenVMS system and the TP Desktop Connector software on the desktop client system.
• DIGITAL 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.
• DIGITAL ACMS for OpenVMS Getting Started
  Provides a high-level discussion and examples of the activities to develop, install, and run a complete application.
• DIGITAL 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, DIGITAL recommends reading the following books before using the TP Desktop Connector for ACMS product:

• DIGITAL ACMS for OpenVMS Writing Applications
  Describes procedures to follow using the Application Development Utility (ADU).
• DIGITAL 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:

• DIGITAL ACMS for OpenVMS Introduction
  Describes basic concepts and terms concerning the ACMS environment.
• DIGITAL 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 DIGITAL ACMS solution. Available through DIGITAL Services.
• DECtp Design Toolkit
  Provides valuable extensions to DECdesign software to help design effective ACMS solutions. Available through DIGITAL Services.

For information on OpenVMS programming tools and DIGITAL 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 DIGITAL 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 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.

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 DIGITAL 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
DIGITAL 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 DIGITAL 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