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.
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.
This guide is intended for application programmers, application designers, and system managers.
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. |
For information on developing DIGITAL ACMS applications, refer to the following manuals:
If you are new to programming with ACMS software, DIGITAL 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 DIGITAL software engineering standards and practices, refer to these documents:
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.
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.
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 |
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.
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. |
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.
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 |
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.
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 |