Compaq TP Desktop Connector AA-PVNFG-TE User manual

CompaqTPDesktopConnector
forACMS
ClientServicesReferenceManual
Order Number: AA–PVNFG–TE
May 2002
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
for ACMS Version 3.2
Compaq Computer Corporation
Houston, Texas

© 2002 Compaq Information Technologies Group, L.P.
Compaq, the Compaq logo, ACMS, ACMS Desktop, ACMSxp, DECnet, the DIGITAL logo,
OpenVMS, and VMScluster are trademarks of Compaq Information Technologies Group, L.P. in
the U.S. and/or other countries.
Microsoft, Windows, Windows NT, and Visual C++ are trademarks of Microsoft Corporation in
the U.S. and/or other countries.
Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems,
Inc., in the U.S. and other countries.
All other product names mentioned herein may be trademarks of their respective companies.
Confidential computer software. Valid license from Compaq required for possession, use, or
copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer
Software Documentation, and Technical Data for Commercial Items are licensed to the U.S.
Government under vendor’s standard commercial license.
Compaq shall not be liable for technical or editorial errors or omissions contained herein. The
information in this document is provided "as is" without warranty of any kind and is subject
to change without notice. The warranties for Compaq products are set forth in the express
limited warranty statements accompanying such products. Nothing herein should be construed
as constituting an additional warranty.

Contents
Preface ..................................................... vii
1 Service Format
1.1 Routine Names . . . ................................... 1–1
1.2 Format . . ........................................... 1–1
1.3 Parameters ......................................... 1–1
1.3.1 Type Entry ....................................... 1–2
1.3.2 Access .......................................... 1–3
1.3.3 Mechanism ....................................... 1–3
1.4 Return Status ....................................... 1–4
1.5 Session Environments ................................. 1–4
2 TP Desktop Connector Portable API Client Services
2.1 Summary of Portable API Client Services .................. 2–1
2.2 Parameter Memory Allocation ........................... 2–2
2.3 Nonblocking Service Usage . . ........................... 2–2
2.3.1 Nonblocking and Blocking Restriction .................. 2–3
2.3.2 Completion Routine Format .......................... 2–3
2.4 Workspace Data Structures . . ........................... 2–4
2.4.1 ACMSDI_WORKSPACE Structure and Initialization
Macro ........................................... 2–4
2.4.2 ACMSDI_WORKSPACE_OPT Structure ................ 2–6
2.4.3 ACMSDI_WORKSPACE_BIND Structure ............... 2–7
2.4.4 ACMSDI_FORM_RECORD_BIND Structure . . . .......... 2–7
2.5 ACMSDI_CALL_OPTION Union Structure ................. 2–8
2.5.1 ACMSDI_OPTION Array . ........................... 2–10
2.6 acmsdi_call_task . . ................................... 2–13
2.7 acmsdi_cancel ....................................... 2–18
2.8 acmsdi_complete_pp ................................... 2–21
2.9 acmsdi_dispatch_message . . . ........................... 2–23
2.10 acmsdi_return_pointer ................................. 2–25
iii

2.11 acmsdi_sign_in ....................................... 2–26
2.12 acmsdi_sign_out ...................................... 2–29
3 Portable API Presentation Procedures
3.1 Summary of Portable API Presentation Procedures ........... 3–1
3.1.1 Return Status Values Expected from Presentation
Procedures ....................................... 3–2
3.1.2 ACMSDI_FORM_RECORD Structure and Macro Call ...... 3–3
3.1.3 Prototypes and Code for Presentation Procedures and
Version Routines . . ................................ 3–3
3.2 Parameter Memory Allocation . . . ........................ 3–3
3.3 Blocking and Nonblocking Usage . ........................ 3–4
3.3.1 Presentation Procedures in a Nonblocking Environment .... 3–4
3.3.2 Nonblocking and Blocking Restriction . . ................ 3–4
3.4 acmsdi_disable ....................................... 3–5
3.5 acmsdi_enable ....................................... 3–6
3.6 acmsdi_read_msg ..................................... 3–9
3.7 acmsdi_receive ....................................... 3–11
3.8 acmsdi_request ...................................... 3–14
3.9 acmsdi_send . ........................................ 3–16
3.10 acmsdi_transceive .................................... 3–19
3.11 acmsdi_write_msg .................................... 3–23
3.12 Version-Checking Routines.............................. 3–25
3.12.1 acmsdi_check_version .............................. 3–25
3.12.2 acmsdi_get_version ................................ 3–27
4 Forced Nonblocking Client Services
4.1 Summary of Forced Nonblocking Procedures ................ 4–1
4.1.1 ACMSDI_FORM_RECORD_BIND Structure ............. 4–2
4.1.2 ACMSDI_WORKSPACE_BIND Structure ............... 4–3
4.2 acmsdi_complete_call . . ................................ 4–4
4.3 acmsdi_bind_enable_args ............................... 4–7
4.4 acmsdi_bind_msg ..................................... 4–10
4.5 acmsdi_bind_receive_args .............................. 4–13
4.6 acmsdi_bind_receive_recs ............................... 4–15
4.7 acmsdi_bind_request_args .............................. 4–17
4.8 acmsdi_bind_request_wksps ............................. 4–19
4.9 acmsdi_bind_send_args ................................ 4–21
4.10 acmsdi_bind_send_recs. ................................ 4–23
4.11 acmsdi_bind_session_id ................................ 4–25
4.12 acmsdi_bind_transceive_args ............................ 4–27
iv

4.13 acmsdi_poll ......................................... 4–30
5 System Management Service on OpenVMS
5.1 ACMSDI$GET_SUBMITTER_INFO . . . ................... 5–2
6 Data Compression Monitor Commands
6.1 EXIT . . . ........................................... 6–2
6.2 HELP . . . ........................................... 6–3
6.3 LIST............................................... 6–4
6.4 RENEW . ........................................... 6–9
6.5 SELECT . ........................................... 6–10
6.6 SET ............................................... 6–13
6.7 SHOW . . ........................................... 6–15
A Compaq ACMS System Status Values
Index
Examples
2–1 Workspace Structure Definition and Initialization ......... 2–5
2–2 Passing Workspaces to a Procedure . ................... 2–5
2–3 ACMSDI_WORKSPACE_OPT Type Definition . . .......... 2–6
2–4 Passing Two Workspaces . ........................... 2–6
2–5 Initializing an Options List .......................... 2–11
2–6 Dynamically Specifying a TCP/IP Port Identifier .......... 2–12
3–1 Form Record Definition and Initialization Macro .......... 3–3
4–1 Form Record Definition . . ........................... 4–3
4–2 Workspace Structure Definition ....................... 4–3
v

Figures
5–1 Submitter Item Descriptor Format .................... 5–3
Tables
1–1 Services Description Parameters ...................... 1–1
1–2 Parameter Data Types .............................. 1–2
1–3 Called Routine Access Methods ....................... 1–3
1–4 Parameter-Passing Mechanisms ...................... 1–4
1–5 Matrix of Services and Environments . . ................ 1–5
2–1 Summary of Portable API Client Services ............... 2–1
2–2 acmsdi_call_task Return Status Values . ................ 2–16
2–3 acmsdi_cancel Return Status Values . . . ................ 2–20
2–4 acmsdi_complete_pp Return Status Values .............. 2–22
2–5 acmsdi_dispatch_message Return Status Values . . . ....... 2–23
2–6 acmsdi_sign_in Return Status Values . . ................ 2–28
2–7 acmsdi_sign_out Return Status Values . ................ 2–30
3–1 Summary of Portable API Presentation Procedures . ....... 3–1
4–1 Summary of Forced Nonblocking Procedures ............. 4–1
4–2 acmsdi_complete_call Return Status Values.............. 4–6
4–3 acmsdi_bind_enable_args Return Status Values . . . ....... 4–9
4–4 acmsdi_bind_msg Return Status Values. ................ 4–12
4–5 acmsdi_bind_receive_args Return Status Values . . . ....... 4–14
4–6 acmsdi_bind_receive_recs Return Status Values . . . ....... 4–16
4–7 acmsdi_bind_request_args Return Status Values . . . ....... 4–18
4–8 acmsdi_bind_request_wksps Return Status Values . ....... 4–20
4–9 acmsdi_bind_send_args Return Status Values ............ 4–22
4–10 acmsdi_bind_send_recs Return Status Values ............ 4–24
4–11 acmsdi_bind_session_id Return Status Values ............ 4–26
4–12 acmsdi_bind_transceive_args Return Status Values . ....... 4–29
4–13 acmsdi_poll Return Status Values ..................... 4–31
5–1 Submitter Information Item Codes .................... 5–3
5–2 ACMSDI$GET_SUBMITTER_INFO Return Status
Values . . ........................................ 5–6
A–1 ACMS System Status Values . ........................ A–1
vi

Preface
This manual provides reference information for the 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,
and 5 Contain the reference information on TP Desktop Connector client services, presentation procedures, action routines, and the Compaq
OpenVMS based system management service.
Chapter 6 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.
vii

•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.
If you are new to programming with ACMS software, Compaq recommends
reading the following books before using the Compaq 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.
For information on OpenVMS programming tools, refer to this document:
•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.
viii

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 parame-
ters, variables, services, or procedures.
ix

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.
Windows When used alone, Windows indicates any supported member
of the family of Microsoft Windows operating systems.
Where necessary, specific Windows operating systems are
mentioned. For a list of Microsoft Windows operating
systems supported by the TP Desktop Connector product,
see the product’s Software Product Description (SPD).
x