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

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.
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.
Service Format 1–1

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 32-bit signed integer
long Synonym for long int
long int 32-bit signed integer (continued on next page)
1–2 Service Format

Table 1–2 (Cont.) Parameter Data Types
Data Type Description
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.
Service Format 1–3

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
Windows long int
OpenVMS long int
Tru64 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
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.
1–4 Service Format

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
(continued on next page)
Service Format 1–5

Table 1–5 (Cont.) Matrix of Services and Environments
Service Availability within Environment
Blocking Nonblocking Forced Nonblocking
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 -
(continued on next page)
1–6 Service Format

Table 1–5 (Cont.) Matrix of Services and Environments
Service Availability within Environment
Blocking Nonblocking Forced Nonblocking
Callbacks
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
Service Format 1–7

2
TP Desktop Connector Portable API Client
Services
This chapter describes the Compaq TP Desktop Connector portable API client
services available on the following desktop systems:
• Microsoft Windows
• Compaq OpenVMS
• Compaq Tru64 UNIX
2.1 Summary of Portable API Client Services
Similar to the Compaq ACMS Service Interface (SI) routines provided on the
Compaq OpenVMS host, the TP Desktop Connector portable API client services
allow you to write a desktop client program on desktop systems without
extensive knowledge of network communications. Table 2–1 summarizes the
TP Desktop Connector portable API client services.
Table 2–1 Summary of Portable API Client Services
Service Description
acmsdi_call_task Sends a request to the TP Desktop Connector gateway
to start a task in a ACMS application. The TP Desktop
Connector client service is either blocking or nonblocking.
Exchange step processing during the task is handled by
the TP Desktop Connector gateway calling customer-
written generic presentation procedures in the desktop
client program.
acmsdi_cancel Used by nonblocking services only. Called by a desktop
application to cancel a currently active ACMS task.
(continued on next page)
TP Desktop Connector Portable API Client Services 2–1

Table 2–1 (Cont.) Summary of Portable API Client Services
Service Description
acmsdi_complete_pp Used by nonblocking environments only. Sends a response
from a presentation procedure request to the TP Desktop
Connector gateway.
acmsdi_dispatch_
message Used by nonblocking environments only. Checks for and processes messages from the TP Desktop Connector
gateway. If no messages have been received from the
gateway, acmsdi_dispatch_message returns immediately.
acmsdi_return_pointer Used by client programs written in Microsoft Visual Basic
to create the workspace array for ACMS_CALL_TASK.
Also used in the forced nonblocking environment to obtain
reference pointers.
acmsdi_sign_in Requests the TP Desktop Connector gateway to sign a user
running a desktop client program in to a ACMS system.
acmsdi_sign_out Requests the TP Desktop Connector gateway to sign a
desktop client program out of a ACMS system.
These calls use the C-language argument-passing standards. Character strings
are NULL-terminated and passed by reference. Workspaces are passed as
structures composed of a length and a pointer field.
2.2 Parameter Memory Allocation
The caller of a TP Desktop Connector client service or a presentation procedure
is responsible for allocating the memory for the parameters of that routine.
For calls to the TP Desktop Connector client services, the desktop client
program must allocate the memory for all parameters passed in, for example,
submitter_id and call_context. For calls to the presentation procedures, the
TP Desktop Connector client services allocate memory for all the parameters
passed and for all workspaces.
2.3 Nonblocking Service Usage
The acmsdi_sign_in, acmsdi_call_task, and acmsdi_sign_out services can be
either blocking, nonblocking, or forced nonblocking. If the desktop client
program supplies the completion_routine parameter to the TP Desktop
Connector client service, the service behaves in the nonblocking fashion. The
TP Desktop Connector client service returns control to the desktop client
program as soon as a request is sent to the TP Desktop Connector gateway.
If the request is sent to the gateway successfully, the TP Desktop Connector
2–2 TP Desktop Connector Portable API Client Services