Compaq TP DESKTOP CONNECTOR AAPVNFGTE User Manual

Compaq TP Desktop Connector  
for ACMS  
Client Services Reference Manual  
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:  
Operating System:  
This is a revised manual.  
Compaq OpenVMS VAX  
Compaq OpenVMS Alpha  
Software Version:  
Compaq TP Desktop Connector  
for ACMS Version 3.2  
Compaq Computer Corporation  
Houston, Texas  
Contents  
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
vii  
1 Service Format  
1.1  
1.2  
1.3  
1.3.1  
1.3.2  
1.3.3  
1.4  
Routine Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
1–1  
1–1  
1–1  
1–2  
1–3  
1–3  
1–4  
1–4  
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Type Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Return Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Session Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
1.5  
2 TP Desktop Connector Portable API Client Services  
2.1  
2.2  
2.3  
2.3.1  
2.3.2  
2.4  
Summary of Portable API Client Services . . . . . . . . . . . . . . . . . .  
Parameter Memory Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Nonblocking Service Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Nonblocking and Blocking Restriction . . . . . . . . . . . . . . . . . .  
Completion Routine Format . . . . . . . . . . . . . . . . . . . . . . . . . .  
Workspace Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
ACMSDI_WORKSPACE Structure and Initialization  
2–1  
2–2  
2–2  
2–3  
2–3  
2–4  
2.4.1  
Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
ACMSDI_WORKSPACE_OPT Structure . . . . . . . . . . . . . . . .  
ACMSDI_WORKSPACE_BIND Structure . . . . . . . . . . . . . . .  
ACMSDI_FORM_RECORD_BIND Structure . . . . . . . . . . . . .  
ACMSDI_CALL_OPTION Union Structure . . . . . . . . . . . . . . . . .  
ACMSDI_OPTION Array . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
acmsdi_call_task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
acmsdi_cancel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
acmsdi_complete_pp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
acmsdi_dispatch_message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
acmsdi_return_pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
2–4  
2–6  
2–7  
2–7  
2–8  
2–10  
2–13  
2–18  
2–21  
2–23  
2–25  
2.4.2  
2.4.3  
2.4.4  
2.5  
2.5.1  
2.6  
2.7  
2.8  
2.9  
2.10  
iii  
2.11  
2.12  
acmsdi_sign_in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
acmsdi_sign_out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
2–26  
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
ACMSDI_FORM_RECORD Structure and Macro Call . . . . . .  
Prototypes and Code for Presentation Procedures and  
3–2  
3–3  
3.1.2  
3.1.3  
Version Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Parameter Memory Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Blocking and Nonblocking Usage . . . . . . . . . . . . . . . . . . . . . . . . .  
Presentation Procedures in a Nonblocking Environment . . . .  
Nonblocking and Blocking Restriction . . . . . . . . . . . . . . . . . .  
acmsdi_disable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
acmsdi_enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
acmsdi_read_msg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
acmsdi_receive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
acmsdi_request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
acmsdi_send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
acmsdi_transceive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
acmsdi_write_msg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Version-Checking Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
acmsdi_check_version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
acmsdi_get_version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
3–3  
3–3  
3–4  
3–4  
3–4  
3–5  
3–6  
3–9  
3–11  
3–14  
3–16  
3–19  
3–23  
3–25  
3–25  
3–27  
3.2  
3.3  
3.3.1  
3.3.2  
3.4  
3.5  
3.6  
3.7  
3.8  
3.9  
3.10  
3.11  
3.12  
3.12.1  
3.12.2  
4 Forced Nonblocking Client Services  
4.1  
Summary of Forced Nonblocking Procedures . . . . . . . . . . . . . . . .  
4–1  
4–2  
4–3  
4–4  
4–7  
4–10  
4–13  
4–15  
4–17  
4–19  
4–21  
4–23  
4–25  
4–27  
4.1.1  
4.1.2  
4.2  
4.3  
4.4  
4.5  
4.6  
4.7  
4.8  
ACMSDI_FORM_RECORD_BIND Structure . . . . . . . . . . . . .  
ACMSDI_WORKSPACE_BIND Structure . . . . . . . . . . . . . . .  
acmsdi_complete_call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
acmsdi_bind_enable_args . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
acmsdi_bind_msg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
acmsdi_bind_receive_args . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
acmsdi_bind_receive_recs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
acmsdi_bind_request_args . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
acmsdi_bind_request_wksps . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
acmsdi_bind_send_args . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
acmsdi_bind_send_recs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
acmsdi_bind_session_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
acmsdi_bind_transceive_args . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
4.9  
4.10  
4.11  
4.12  
iv  
4.13  
acmsdi_poll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
4–30  
5–2  
5 System Management Service on OpenVMS  
5.1  
ACMSDI$GET_SUBMITTER_INFO . . . . . . . . . . . . . . . . . . . . . .  
6 Data Compression Monitor Commands  
6.1  
6.2  
6.3  
6.4  
6.5  
6.6  
6.7  
EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
6–2  
6–3  
6–4  
HELP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
LIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
RENEW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
SELECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
SET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
SHOW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
6–9  
6–10  
6–13  
6–15  
A Compaq ACMS System Status Values  
Index  
Examples  
2–1  
2–2  
2–3  
2–4  
2–5  
2–6  
3–1  
4–1  
4–2  
Workspace Structure Definition and Initialization . . . . . . . . .  
2–5  
2–5  
Passing Workspaces to a Procedure . . . . . . . . . . . . . . . . . . . .  
ACMSDI_WORKSPACE_OPT Type Definition . . . . . . . . . . . .  
Passing Two Workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Initializing an Options List . . . . . . . . . . . . . . . . . . . . . . . . . .  
Dynamically Specifying a TCP/IP Port Identifier . . . . . . . . . .  
Form Record Definition and Initialization Macro . . . . . . . . . .  
Form Record Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Workspace Structure Definition . . . . . . . . . . . . . . . . . . . . . . .  
2–6  
2–6  
2–11  
2–12  
3–3  
4–3  
4–3  
v
Figures  
5–1  
Submitter Item Descriptor Format . . . . . . . . . . . . . . . . . . . .  
5–3  
Tables  
1–1  
1–2  
1–3  
1–4  
1–5  
2–1  
2–2  
2–3  
2–4  
2–5  
2–6  
2–7  
3–1  
4–1  
4–2  
4–3  
4–4  
4–5  
4–6  
4–7  
4–8  
4–9  
4–10  
4–11  
4–12  
4–13  
5–1  
5–2  
Services Description Parameters . . . . . . . . . . . . . . . . . . . . . .  
Parameter Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Called Routine Access Methods . . . . . . . . . . . . . . . . . . . . . . .  
Parameter-Passing Mechanisms . . . . . . . . . . . . . . . . . . . . . .  
Matrix of Services and Environments . . . . . . . . . . . . . . . . . .  
Summary of Portable API Client Services . . . . . . . . . . . . . . .  
acmsdi_call_task Return Status Values . . . . . . . . . . . . . . . . .  
acmsdi_cancel Return Status Values . . . . . . . . . . . . . . . . . . .  
acmsdi_complete_pp Return Status Values . . . . . . . . . . . . . .  
acmsdi_dispatch_message Return Status Values . . . . . . . . . .  
acmsdi_sign_in Return Status Values . . . . . . . . . . . . . . . . . .  
acmsdi_sign_out Return Status Values . . . . . . . . . . . . . . . . .  
Summary of Portable API Presentation Procedures . . . . . . . .  
Summary of Forced Nonblocking Procedures . . . . . . . . . . . . .  
acmsdi_complete_call Return Status Values . . . . . . . . . . . . . .  
acmsdi_bind_enable_args Return Status Values . . . . . . . . . .  
acmsdi_bind_msg Return Status Values . . . . . . . . . . . . . . . . .  
acmsdi_bind_receive_args Return Status Values . . . . . . . . . .  
acmsdi_bind_receive_recs Return Status Values . . . . . . . . . .  
acmsdi_bind_request_args Return Status Values . . . . . . . . . .  
acmsdi_bind_request_wksps Return Status Values . . . . . . . .  
acmsdi_bind_send_args Return Status Values . . . . . . . . . . . .  
acmsdi_bind_send_recs Return Status Values . . . . . . . . . . . .  
acmsdi_bind_session_id Return Status Values . . . . . . . . . . . .  
acmsdi_bind_transceive_args Return Status Values . . . . . . . .  
acmsdi_poll Return Status Values . . . . . . . . . . . . . . . . . . . . .  
Submitter Information Item Codes . . . . . . . . . . . . . . . . . . . .  
1–1  
1–2  
1–3  
1–4  
1–5  
2–1  
2–16  
2–20  
2–22  
2–23  
2–28  
2–30  
3–1  
4–1  
4–6  
4–9  
4–12  
4–14  
4–16  
4–18  
4–20  
4–22  
4–24  
4–26  
4–29  
4–31  
5–3  
ACMSDI$GET_SUBMITTER_INFO Return Status  
Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
5–6  
A–1  
A–1  
ACMS System Status Values . . . . . . . . . . . . . . . . . . . . . . . . .  
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, Contain the reference information on TP Desktop Connector client  
and 5  
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:  
Com pa q TP Desktop Con n ector for ACMS Client Application  
Programming Guide  
Provides information for designing, coding, and implementing a TP Desktop  
Connector solution.  
vii  
Com pa q TP Desktop Con n ector 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.  
Com pa q TP Desktop Con n ector 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.  
Com pa q TP Desktop Con n ector 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:  
Com pa q ACMS for Open VMS Writing Applications  
Describes procedures to follow using the Application Development Utility  
(ADU).  
Com pa q ACMS for Open VMS 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:  
Com pa q ACMS for Open VMS Introduction  
Describes basic concepts and terms concerning the ACMS environment.  
Com pa q ACMS for Open VMS 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  
Ctrl/x  
A key name in a box indicates that you press that key on  
the keyboard.  
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 products 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  
Method by which a parameter is passed to the called routine  
Mechanism  
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)  
Union to specify call task options  
ACMSDI_CALL_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  
ACMSDI_WORKSPACE_OPT  
Structure defined in the ACMSDI.H and  
ACMSDI.BAS include files (see Section 4.1.2)  
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  
Synonym for long int  
32-bit signed integer  
(continued on next page)  
long  
long int  
1–2 Service Format  
Table 1–2 (Cont.) Parameter Data Types  
Data Type  
Description  
longword  
ptr  
32-bit unsigned integer  
Longword pointer to data buffer  
Synonym for short int  
short  
short int  
unsigned long int  
void *  
16-bit signed integer  
32-bit unsigned integer  
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  
long int  
long int  
OpenVMS  
Tru64 UNIX  
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 Com pa q TP Desktop Con n ector 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  
yes  
yes  
yes  
See description in Section 2.6  
acmsdi_cancel  
See description in Section 2.7  
-
yes  
yes  
yes  
-
yes  
acmsdi_complete_pp  
See description in Section 2.8  
-
yes  
acmsdi_dispatch_message  
See description in Section 2.9  
-
yes  
yes  
yes  
-
-
acmsdi_return_pointer  
See description in Section 2.10  
yes  
acmsdi_sign_in  
See description in Section 2.11  
yes  
yes  
-
yes  
acmsdi_sign_out  
See description in Section 2.12  
yes  
acmsdi_poll  
yes  
See description in Section 4.13  
acmsdi_complete_call  
-
-
yes  
See description in Section 4.2  
acmsdi_bind_enable_args  
-
-
yes  
See description in Section 4.3  
acmsdi_bind_send_args  
-
-
yes  
See description in Section 4.9  
(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  
-
-
yes  
See description in Section 4.5  
acmsdi_bind_transceive_args  
See description in Section 4.12  
-
-
-
-
-
-
-
-
-
-
-
-
-
-
yes  
yes  
yes  
yes  
yes  
yes  
yes  
acmsdi_bind_msg  
See description in Section 4.4  
acmsdi_bind_request_args  
See description in Section 4.7  
acmsdi_bind_session_id  
See description in Section 4.11  
acmsdi_bind_send_recs  
See description in Section 4.10  
acmsdi_bind_receive_recs  
See description in Section 4.6  
acmsdi_bind_request_wksps  
See description in Section 4.8  
Callbacks  
acmsdi_disable  
See description in Section 3.4  
-
-
-
-
-
-
yes  
yes  
yes  
yes  
yes  
yes  
-
acmsdi_enable  
See description in Section 3.5  
-
acmsdi_read_msg  
See description in Section 3.6  
-
acmsdi_receive  
See description in Section 3.7  
-
acmsdi_request  
See description in Section 3.8  
-
acmsdi_send  
-
See description in Section 3.9  
(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  
yes  
yes  
yes  
-
-
acmsdi_write_msg  
See description in Section 3.11  
acmsdi_check_version  
See description in Section 3.12.1  
-
acmsdi_get_version(back end)  
See description in Section 3.12.2  
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  
acmsdi_sign_out  
Requests the TP Desktop Connector gateway to sign a user  
running a desktop client program in to a ACMS system.  
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  
client service returns the ACMSDI_PENDING status. If a status other than  
ACMSDI_PENDING is returned, the completion routine is not called.  
If nonblocking calls are active, use the acmsdi_dispatch_message service to  
poll for responses from the TP Desktop Connector gateway. When a response  
is received, acmsdi_dispatch_message calls the appropriate customer-supplied  
completion routine. If the desktop client program supplies the completion_  
status parameter on the initial TP Desktop Connector client service call,  
the TP Desktop Connector client services set the completion_status to the  
final completion status for the service and immediately call the completion  
routine. See Com pa q TP Desktop Con n ector for ACMS Client Application  
Programming Guide for descriptions and examples.  
The forced nonblocking services extend the portable API to support both  
exchange steps and nonblocking execution of task calls for development tools  
that do not support pointer data types or whose memory management routines  
relocate data. You can specify a forced nonblocking session with the acmsdi_  
sign_in service by using the ACMSDI_OPTION, ACMSDI_OPT_NONBLK. Do  
not specify a completion routine in a forced nonblocking session as this will  
result in an error. See Chapter 4 for more information.  
2.3.1 Nonblocking and Blocking Restriction  
All calls using the same desktop client program and TP Desktop Connector  
gateway connection must be either blocking, nonblocking, or forced  
nonblocking. These types of service calls cannot be mixed for a desktop  
client program and TP Desktop Connector gateway pair. See Table 1–5 for  
the list of service calls available for each type of session. If a desktop client  
program connects to two different TP Desktop Connector gateways, it can  
mix service call types, using blocking calls to interact with one TP Desktop  
Connector gateway and nonblocking calls to interact with the other TP Desktop  
Connector gateway.  
2.3.2 Completion Routine Format  
For nonblocking service requests, the acmsdi_dispatch_message service calls  
the customer-supplied completion routine when a response is received from  
the TP Desktop Connector gateway. The completion routine has the following  
format:  
void completion_routine (call_context)  
Parameters  
TP Desktop Connector Portable API Client Services 2–3  
call_context  
Type: void *  
Access: r ea d  
Mechanism: by va lu e  
Supplies application-specific context to the completion routine. If specified on  
acmsdi_call_task, acmsdi_sign_in, acmsdi_cancel, or acmsdi_sign_out service,  
the call_context is passed by the TP Desktop Connector client services to the  
completion routine.  
Return Status  
The customer-supplied completion routine does not return a status value.  
2.4 Workspace Data Structures  
This section describes the following workspace data structures:  
ACMSDI_WORKSPACE  
ACMSDI_WORKSPACE_OPT  
ACMSDI_WORKSPACE_BIND  
ACMSDI_FORM_RECORD_BIND  
2.4.1 ACMSDI_WORKSPACE Structure and Initialization Macro  
Defined in the ACMSDI.H file, the ACMSDI_WORKSPACE type declares  
workspaces passed to tasks using the acmsdi_call_task service and workspaces  
passed from tasks to acmsdi_request presentation procedures.  
The code in Example 2–1 defines the ACMSDI_WORKSPACE type and  
an ACMSDI_INIT_WORKSPACE macro used to initialize the workspace  
structure.  
2–4 TP Desktop Connector Portable API Client Services  
Example 2–1 Workspace Structure Definition and Initialization  
typedef struct {  
unsigned int length;  
/** length of workspace **/  
/** pointer to workspace **/  
void *data;  
} ACMSDI_WORKSPACE;  
.
.
.
#define ACMSDI_INIT_WORKSPACE(_wksp, _rec)\  
{\  
_wksp.length = sizeof(_rec);\  
_wksp.record = &(_rec);\  
}
To pass more than one workspace to a procedure, use an array of the ACMSDI_  
WORKSPACE structures. Example 2–2 passes two workspaces.  
Example 2–2 Passing Workspaces to a Procedure  
ACMSDI_WORKSPACE wksp_array[2];  
struct {  
char ctrl_key[5];  
char error_message[80];  
} control_wksp;  
struct {  
int id_number;  
char first_name[15];  
char last_name[25];  
} employee_record;  
ACMSDI_INIT_WORKSPACE (wksp_array[0], control_wksp);  
ACMSDI_INIT_WORKSPACE (wksp_array[1], employee_record);  
The array wksp_array is defined with two elements of type ACMSDI_  
WORKSPACE. The structure definitions control_wksp and employee_record  
define the elements of the array. The two macro ACMSDI_INIT_WORKSPACE  
calls initialize the array of structures.  
TP Desktop Connector Portable API Client Services 2–5  
2.4.2 ACMSDI_WORKSPACE_OPT Structure  
The ACMSDI.H file contains the definition of the ACMSDI_WORKSPACE_OPT  
type you use to declare workspaces passed to tasks using the ACMSDI_CALL_  
TASK service. You can use ACMSDI_WORKSPACE_OPT instead of ACMSDI_  
WORKSPACE. Only task calls that use the ACMSDI_TASK_OPTIONS flag to  
indicate unidirectional workspaces can use this structure. Example 2–3 shows  
the ACMSDI_WORKSPACE_OPT type definition and the definition of a macro  
to initialize the workspace structure.  
Example 2–3 ACMSDI_WORKSPACE_OPT Type Definition  
#define ACMSDI_ACCESS_READ  
’1’  
/* read-only access */  
/* write-only access */  
/* modify (read and write) */  
#define ACMSDI_ACCESS_WRITE ’2’  
#define ACMSDI_ACCESS_MODIFY ’3’  
.
.
.
typedef char ACMSDI_ACCESS_TYPE;  
typedef struct {  
unsigned int length;  
ACMSDI_ACCESS_TYPE access;  
void *data;  
} ACMSDI_WORKSPACE_OPT;  
.
.
.
#define ACMSDI_INIT_WORKSPACE_OPT(_wksp, _rec, _access)\  
{\  
_wksp.length = sizeof(_rec);\  
_wksp.access = _access;\  
_wksp.data  
= &(_rec);\  
}
To pass more than one workspace to a procedure, use an array of the type  
ACMSDI_WORKSPACE_OPT. Example 2–4 passes two workspaces.  
Example 2–4 Passing Two Workspaces  
ACMSDI_WORKSPACE_OPT wksp_array[2];  
struct {  
char ctrl_key[5];  
char error_message[80];  
} control_wksp;  
(continued on next page)  
2–6 TP Desktop Connector Portable API Client Services  
Example 2–4 (Cont.) Passing Two Workspaces  
struct {  
int id_number;  
char first_name[15];  
char last_name[25];  
} employee_record;  
ACMSDI_INIT_WORKSPACE_OPT (wksp_array[0], control_wksp, ACMSDI_ACCESS_READ);  
ACMSDI_INIT_WORKSPACE_OPT (wksp_array[1], employee_record, ACMSDI_ACCESS_WRITE);  
2.4.3 ACMSDI_WORKSPACE_BIND Structure  
The ACMSDI_WORKSPACE_BIND structure locates workspace buffers  
and specifies the sizes of workspaces during acmsdi_bind_request_wksps  
operations. Like the ACMSDI_FORM_RECORD_BIND structure, the  
ACMSDI_WORKSPACE_BIND structure contains a field where the length  
of the TDMS exchange step workspace is returned. If the length differs from  
the buffer length, TP Desktop Connector truncates the resultant workspaces or  
buffers are not completely filled.  
The following example shows the C language definition of this structure as it  
appears in the acmsdi.h file:  
typedef struct {  
unsigned int buffer_len;  
unsigned int wksp_len;  
/* length of caller’s buffer */  
/* actual length of the workspace */  
void  
*data;  
} ACMSDI_WORKSPACE_BIND;  
2.4.4 ACMSDI_FORM_RECORD_BIND Structure  
The ACMSDI_FORM_RECORD_BIND structure locates form record buffers  
and specifies their sizes during acmsdi_bind_send_recs and acmsdi_bind_  
receive_recs operations. ACMSDI_FORM_RECORD_BIND serves the same  
purpose as ACMSDI_FORM_RECORD with one additional feature. It contains  
an additional field, rec_len, with which the TP Desktop Connector client  
services return the actual length of the form record as it is returned from  
the back-end application. You can compare this length against the client  
application buffer length to see if the buffer is large enough, too large, or  
exactly the right size to contain the form record. If the buffer size is too small,  
the form record is truncated to fit the buffer. If the buffer size is too large, the  
buffer is not completely filled.  
TP Desktop Connector Portable API Client Services 2–7  
You can use the ACMSDI_FORM_RECORD_BIND structure to locate send  
control text and receive control text buffers. Both acmsdi_bind_send_args and  
acmsdi_bind_receive_args services contain arguments to specify whether or not  
to transfer control text. If you specify to transfer control text, the following  
rules apply:  
ACMSDI_FORM_RECORD_BIND structure for the control text must be  
the first one in the array of such structures passed on the call.  
After the call completes, the record length field (rec_len) contains the send  
control text count or the receive control text count instead of the length of  
the record.  
The following example shows the C language definition of this structure as it  
appears in the acmsdi.h file:  
typedef struct {  
unsigned int buffer_len;  
unsigned int rec_len;  
void  
/* length of caller’s record buffer */  
/* actual length of the form record */  
*data_record;  
unsigned int shadow_buffer_len;  
unsigned int shadow_rec_len;  
/* length of caller’s shadow buffer */  
/* actual length of shadow record */  
void  
*shadow_record;  
} ACMSDI_FORM_RECORD_BIND;  
2.5 ACMSDI_CALL_OPTION Union Structure  
ACMSDI_CALL_OPTION union is a parameter that is passed to the ACMSDI_  
CALL_TASK service to enable TP Desktop Connector functions, such as  
optimizing unidirectional workspace traffic on the call to the acmsdi_call_task  
client service. The include file ACMSDI.H contains the definition for the  
ACMSDI_CALL_OPTION union.  
ACMSDI_CALL_OPTION contains several structures with the option variables,  
whose values determine the type of option being selected. Specify the values  
for the option variable using the following constants defined in the ACMSDI.H  
include file:  
2–8 TP Desktop Connector Portable API Client Services  
Option  
Description  
ACMSDI_CALL_OPT_END_LIST  
Ends options list  
ACMSDI_CALL_OPT_OPTIMIZE_WKSPS  
Enables unidirectional workspace  
optimization  
ACMSDI_CALL_OPT_ENABLE  
Pointer to enable function  
ACMSDI_CALL_OPT_DISABLE  
ACMSDI_CALL_OPT_SEND  
Pointer to disable function  
Pointer to send function  
ACMSDI_CALL_OPT_RECEIVE  
ACMSDI_CALL_OPT_TDMS_READ  
ACMSDI_CALL_OPT_TDMS_WRITE  
ACMSDI_CALL_OPT_TRANSCEIVE  
ACMSDI_CALL_OPT_REQUEST  
ACMSDI_CALL_OPT_CHECK_VERSION  
ACMSDI_CALL_OPT_PASS_TID  
ACMSDI_CALL_OPT_COMPRESS_WKSPS  
Pointer to receive function  
Pointer to TDMS read function  
Pointer to TDMS write function  
Pointer to transceive function  
Pointer to TDMS request function  
Version checking routine  
TID of distributed transaction  
Activate workspace compression  
To select options:  
1. Declare an array of at least two elements of the type ACMSDI_CALL_  
OPTION.  
2. Specify in the option variable the name for the structure being used.  
3. Specify the address for the malloc routine or password expiring buffer, if  
these options are being used.  
4. End an options list by assigning ACMSDI_CALL_OPT_END_LIST to the  
option variable in the last array element.  
The following example shows the initialization of an options list used to enable  
unidirectional workspace handling:  
ACMSDI_CALL_OPTION call_options[2];  
call_options[0].option = ACMSDI_CALL_OPT_OPTIMIZE_WKSPS;  
call_options[1].option = ACMSDI_CALL_OPT_END_LIST;  
TP Desktop Connector Portable API Client Services 2–9  
Caution  
Use the ACMSDI_CALL_OPT_OPTIMIZE_WKSPS option and the  
ACMSDI_WORKSPACE_OPT type definition together to optimize  
unidirectional workspace traffic. Do not use one without the other.  
The acmsdi_call_task client service uses the presence or absence of  
the workspace optimization option to decide which data type has been  
passed in the workspaces argument. Using either one without the  
other produces unpredictable results.  
2.5.1 ACMSDI_OPTION Array  
ACMSDI_OPTION array is a parameter that is passed to the ACMSDI_  
SIGN_IN service to enable TP Desktop Connector functions, such as enabling  
password expiration checking on the call to acmsdi_call_task client service.  
The include file ACMSDI.H contains the definition for the ACMSDI_OPTION  
array.  
The ACMSDI_OPTION array is a union containing multiple structures and an  
option variable, the value of which defines the type of option being selected.  
Specify the values for the option variable using the following constants defined  
in the include file ACMSDI.H:  
Constant  
Description  
ACMSDI_OPT_CHECK_VERSION  
ACMSDI_OPT_COMMID  
Enables version checking  
Supplies communications device id or  
TCP/IP comm port  
ACMSDI_OPT_END_LIST  
Ends options list  
ACMSDI_OPT_FREE_ROUTINE  
ACMSDI_OPT_MALLOC_ROUTINE  
ACMSDI_OPT_NONBLK  
Enables user-defined memory deallocation  
Enables user-defined memory allocation  
Enables a forced nonblocking session  
ACMSDI_OPT_PWD_EXPIRING  
Enables checking for passwords that are  
about to expire  
2–10 TP Desktop Connector Portable API Client Services  
To select options:  
1. Declare an array of at least two elements of the type ACMSDI_OPTION.  
2. Specify in the option variable the name tag for the structure being used.  
3. End an options list by assigning ACMSDI_OPT_END_LIST to the option  
variable in the last array element.  
Example 2–5 initializes an options list to enable version checking, user-defined  
memory allocation, and password expiration checking.  
Example 2–5 Initializing an Options List  
void *my_malloc_routine(int size);  
long pwd_exp_buffer;  
void my_free_routine(void *ptr);  
ACMSDI_OPTION options[5];  
options[0].option = ACMSDI_OPT_CHECK_VERSION;  
options[1].option = ACMSDI_OPT_MALLOC_ROUTINE;  
options[1].malloc_routine.address = my_malloc_routine;  
options[2].option = ACMSDI_OPT_FREE_ROUTINE;  
options[2].free_routine.address = my_free_routine;  
options[3].option = ACMSDI_OPT_PWD_EXPIRING;  
options[3].pwd_expiring_hrs.address = &pwd_exp_buffer;  
options[4].option = ACMSDI_OPT_END_LIST;  
You can provide the TCP/IP port number during sign-in by using the ACMSDI_  
OPT_COMMID option. Example 2–6 shows how to do this in C.  
Note  
This option is usable with forced nonblocking calls only.  
If the environmental variable ACMSDI_TCPIP_PORT_host_node is defined,  
the option specified on the acmsdi_sign_in call takes precedence. If neither the  
environmental variable nor the sign-in option is specified, the default TCP/IP  
port number, 1023, is used.  
TP Desktop Connector Portable API Client Services 2–11  
Example 2–6 Dynamically Specifying a TCP/IP Port Identifier  
int status;  
ACMSDI_SUBMITTER_ID subm_id;  
long tcpip_port = 1000;  
ACMSDI_OPTION options[2];  
options[0].option = ACMSDI_OPT_COMMID;  
options[0].CommID = tcpip_port;  
options[1].option = ACMSDI_OPT_END_LIST;  
status = acmsdi_sign_in ("N2001", /* ACMS Desktop Gateway node */  
"HAL", /* username */  
"HELLO_DAVE", /* password */  
options, /* sign in options */  
&subm_id, /* submitter id */  
0, 0, 0);  
2–12 TP Desktop Connector Portable API Client Services  
acmsdi_call_task  
2.6 acmsdi_call_task  
TP Desktop Connector client programs call this service to execute a task in a  
ACMS application.  
Format  
acmsdi_call_task (submitter_id,  
[call_options],  
task_name,  
application_name,  
selection_string,  
status_message,  
workspace_count,  
[workspaces],  
[call_id],  
[completion_status],  
[completion_routine],  
1
[call_context])  
Parameters  
submitter_id  
Type: ACMSDI_SUBMITTER_ID  
Access: r ea d  
Mechanism: by r efer en ce  
The submitter_id returned by the acmsdi_sign_in service.  
call_options  
Type: ACMSDI_CALL_OP TION  
Access: r ea d  
Mechanism: by r efer en ce  
An array of ACMSDI_CALL_OPTION elements that either enables  
unidirectional workspace optimization or defines presentation procedure  
addresses. The include file ACMSDI.H contains the definition for the  
ACMSDI_CALL_OPTION type. If you use the options array to enable  
unidirectional workspaces, use the ACMSDI_WORKSPACE_OPT type in  
the workspace list. See Section 2.4.2 and Section 2.5 for more information.  
1
For nonblocking only, see Section 2.3.  
TP Desktop Connector Portable API Client Services 2–13  
acmsdi_call_task  
task_name  
Type: ch a r *  
Access: r ea d  
Mechanism: by r efer en ce  
The name of the task to execute. Maximum length is 31.  
application_name  
Type: ch a r *  
Access: r ea d  
Mechanism: by r efer en ce  
The specification of a ACMS application in which the task resides. The  
application name must be a valid application specification on the submitter  
node. It can take the form NODE::APPLICATION, or can be specified using a  
logical name that is translated by the ACMS Central Controller (ACC) on the  
submitter node. Maximum length is 80.  
selection_string  
Type: ch a r *  
Access: r ea d  
Mechanism: by r efer en ce  
Used by the desktop client program to pass additional information to the task.  
Maximum length is 256.  
status_message  
Type: ch a r *  
Access: w r ite  
Mechanism: by r efer en ce  
A buffer to receive the message text associated with the task completion status.  
The message text returned is either the text associated with a TP Desktop  
Connector error or the message text returned from a ACMS application.  
Required length is 80.  
Caution  
If the full space is not allocated, the TP Desktop Connector client  
services write past the end of the allocated string and can cause the  
application to fail. Ensure that the desktop client program allocates  
the required length of space.  
2–14 TP Desktop Connector Portable API Client Services  
acmsdi_call_task  
workspace_count  
Type: lon g in t  
Access: r ea d  
Mechanism: by va lu e  
The decimal number of workspaces being passed to the task.  
workspaces  
Type: ACMSDI_WORKSPACE or ACMSDI_WORKSPACE_OP T a r r a y  
Access: r ea d /w r ite  
Mechanism: by r efer en ce  
One or more optional workspaces to be passed to the task. You need to typecast  
your array to void *. The workspaces must be specified in the same order as  
they are declared in the task definition, and must match the number specified  
in the workspace_count parameter. If you use the ACMSDI_WORKSPACE_  
OPT type, you must set the call_options parameter to allow unidirectional  
workspaces.  
call_id  
Type: ACMSDI_CALL_ID  
Access: w r ite  
Mechanism: by r efer en ce  
A structure defined in the ACMSDI.H include file into which the acmsdi_call_  
task service writes a newly created call identification, a handle used by the TP  
Desktop Connector client services to identify an active call for a submitter.  
completion_status  
Type: in t  
Access: w r ite  
Mechanism: by r efer en ce  
The final status of the TP Desktop Connector client service. In the blocking  
environment, the completion_status parameter is set to zero when the service  
starts successfully.  
When the service completes, the completion_status parameter contains the final  
status. See Table 2–2 for the list of return status values.  
When a task is canceled, the TP Desktop Connector gateway reports a specific  
error, where possible. If the gateway cannot convert a ACMS error to a specific  
TP Desktop Connector status, it returns ACMSDI_TASK_FAILED to the  
desktop client program.  
TP Desktop Connector Portable API Client Services 2–15  
acmsdi_call_task  
completion_routine  
Type: fu n ction a d d r ess  
Access: r ea d  
1
Mechanism: by va lu e  
Address of a function to be called when the service completes. The completion_  
routine is called by the acmsdi_dispatch_message service when the "End of  
Task" message is received from the TP Desktop Connector gateway.  
call_context  
Type: void *  
Access: r ea d  
Mechanism: by va lu e  
Optional parameter passed to presentation procedures and completion routines  
to identify the call. Use this parameter to supply an application-specific context  
for the call.  
Return Status  
The status values returned by the acmsdi_call_task service are listed in  
Table 2–2.  
Table 2–2 acmsdi_call_task Return Status Values  
Status  
Description  
ACMSDI_APPLDEAD  
ACMSDI_CALLACTV  
ACMSDI_INSUFPRM  
ACMSDI_INTERNAL  
ACMSDI_INVOPTION  
ACMSDI_INVSUBID  
ACMSDI_MIXEDMODE  
Application stopped unexpectedly.  
Call is already active.  
Insufficient parameters.  
Internal TP Desktop Connector error.  
Invalid item in options list.  
Invalid or obsolete submitter identification.  
All calls on a connection must be either  
blocking or nonblocking.  
ACMSDI_NOMEMORY  
ACMSDI_NORMAL  
Insufficient memory to complete requests.  
Normal successful completion.  
Application not found.  
ACMSDI_NOSUCH_APPL  
(continued on next page)  
1
For nonblocking only, see Section 2.3. Not applicable to forced nonblocking and will  
cause an error if supplied.  
2–16 TP Desktop Connector Portable API Client Services  
acmsdi_call_task  
Table 2–2 (Cont.) acmsdi_call_task Return Status Values  
Status  
Description  
ACMSDI_NOSUCH_TASK  
Task not found.  
ACMSDI_OPR_CANCELLED Operator canceled task.  
ACMSDI_PENDING  
Successful operation pending nonblocking  
completion. The final status is in the  
completion status parameter.  
ACMSDI_SECCHK  
Task security check failed.  
ACMSDI_SIGNINACTV  
ACMSDI_SIGNOUTACTV  
ACMSDI_SRVDEAD  
Request is invalid while the sign-in is active.  
Request is invalid while the sign-out is active.  
Node name is invalid, or TP Desktop  
Connector gateway is not running on the  
specified node, or the network link terminated.  
ACMSDI_TASK_ABORT  
Task completed abnormally.  
ACMSDI_TASK_CANCELLED Task was canceled.  
ACMSDI_TASK_FAILED  
ACMSDI_TASK_SP_DIED  
Task failed during execution.  
Task was canceled when TP Desktop  
Connector gateway process died.  
TP Desktop Connector Portable API Client Services 2–17  
acmsdi_cancel  
2.7 acmsdi_cancel  
TP Desktop Connector client programs call this service in a nonblocking or  
forced nonblocking environment to cancel a currently active ACMS task. Use  
the acmsdi_cancel service only if you invoke a task using nonblocking services.  
Do not use the acmsdi_cancel service from a presentation procedure or from an  
asynchronous completion routine.  
Format  
acmsdi_cancel (submitter id,  
call_id,  
[cancel_reason],  
reserved,  
[completion_status],  
completion_routine,  
1
[call_context])  
Parameters  
submitter_id  
Type: ACMSDI_SUBMITTER_ID  
Access: r ea d  
Mechanism: by r efer en ce  
The submitter_id for the session associated with the task that is being canceled.  
call_id  
Type: ACMSDI_CALL_ID  
Access: r ea d  
Mechanism: by r efer en ce  
The call_id for the task that is being canceled, which was passed back on the  
acmsdi_call_task service.  
cancel_reason  
Type: lon g in t  
Access: r ea d  
Mechanism: by va lu e  
Optional parameter containing the status value of the reason code for the  
cancel request. This value is passed to the Application Execution Controller  
(EXC) by the TP Desktop Connector gateway. The default is ACMSDI_CALL_  
CANCELED, "the task was canceled by the task submitter".  
1
For nonblocking only, see Section 2.3.  
2–18 TP Desktop Connector Portable API Client Services  
acmsdi_cancel  
reserved  
Type:  
Access:  
Mechanism:  
This parameter is reserved for future use. Specify as NULL.  
completion_status  
Type: lon g in t  
Access: w r ite  
Mechanism: by r efer en ce  
Optional parameter to contain the final completion status of the service.  
The completion_status is set to ACMSDI_PENDING when the service starts  
successfully. When the service is successful, completion_status is set to 0.  
completion_routine  
Type: fu n ction a d d r ess  
1
Access: r ea d  
Mechanism: by va lu e  
Address of a function to be called when the service completes. The completion_  
routine is called by the ACMSDI_DISPATCH_MESSAGE service when the  
appropriate reply is received from the TP Desktop Connector gateway on the  
OpenVMS system.  
call_context  
Type: void *  
Access: r ea d  
Mechanism: by va lu e  
Optional parameter that is passed to the completion_routine to identify the  
call. You can use this to supply application-specific context for the call that is  
being canceled.  
Return Status  
The status values returned by the acmsdi_cancel service are listed in  
Table 2–3.  
1
For nonblocking only, see Section 2.3. Not applicable to forced nonblocking and will  
cause an error if supplied.  
TP Desktop Connector Portable API Client Services 2–19  
acmsdi_cancel  
Table 2–3 acmsdi_cancel Return Status Values  
Status  
Description  
ACMSDI_CANCELACTV  
ACMSDI_EXCHACTV  
Cancel already in progress.  
Service cannot be called from presentation  
procedure.  
ACMSDI_INSUFPRM  
ACMSDI_INTERNAL  
ACMSDI_INVCALLID  
ACMSDI_INVSUBID  
ACMSDI_NOMEMORY  
ACMSDI_NORMAL  
ACMSDI_PENDING  
Insufficient parameters.  
Internal ACMS error.  
Invalid or obsolete call identification.  
Invalid or obsolete submitter identification.  
Insufficient memory to complete requests.  
Normal successful completion.  
Successful operation pending nonblocking  
completion. The final status is in the  
completion status parameter.  
ACMSDISIGNINACTV  
ACMSDISIGNOUTACTV  
ACMSDI_SRVDEAD  
Request is invalid while the sign-in is active.  
Request is invalid while sign-out is active.  
Node name is invalid, or the TP Desktop  
Connector gateway is not running on the  
specified node.  
2–20 TP Desktop Connector Portable API Client Services  
acmsdi_complete_pp  
2.8 acmsdi_complete_pp  
TP Desktop Connector client programs call this nonblocking service to complete  
exchange step processing for a submitter. An application must call this  
service to complete an outstanding presentation procedure request from  
the TP Desktop Connector gateway in a nonblocking or forced nonblocking  
environment (see Com pa q TP Desktop Con n ector for ACMS Client  
Application Programming Guide.  
Format  
acmsdi_complete_pp (call_id,  
pp_status)  
Parameters  
call_id  
Type: ACMSDI_CALL_ID  
Access: r ea d  
Mechanism: by r efer en ce  
The call_id parameter is passed back on the acmsdi_call_task service.  
pp_status  
Type: lon g in t  
Access: r ea d  
Mechanism: by va lu e  
The completion status of the presentation procedure. The pp_status parameter  
is returned to the ACMS task as the completion status for the current exchange  
step. A valid OpenVMS status value is returned to the task.  
Return Status  
The status values returned by the acmsdi_complete_pp service are listed in  
Table 2–4.  
TP Desktop Connector Portable API Client Services 2–21  
acmsdi_complete_pp  
Table 2–4 acmsdi_complete_pp Return Status Values  
Status  
Description  
ACMSDI_INSUFPRM  
ACMSDI_INTERNAL  
ACMSDI_INVCALLID  
ACMSDI_INVSUBID  
ACMSDI_NOMEMORY  
ACMSDI_NOPPACTV  
ACMSDI_NORMAL  
ACMSDI_SRVDEAD  
Insufficient parameters.  
Internal TP Desktop Connector error.  
Invalid or obsolete call identification.  
Invalid or obsolete submitter identification.  
Insufficient memory to complete requests.  
No presentation procedure active for this call.  
Normal successful completion.  
Node name is invalid, or the TP Desktop  
Connector gateway is not running on the  
specified node, or the network link terminated.  
2–22 TP Desktop Connector Portable API Client Services  
acmsdi_dispatch_message  
2.9 acmsdi_dispatch_message  
TP Desktop Connector client programs call this nonblocking service to check  
for and process messages sent from a TP Desktop Connector gateway to an  
active submitter in the desktop application. The application must periodically  
call this service in a nonblocking environment to check for completion of  
outstanding acmsdi_sign_in, acmsdi_call_task, and acmsdi_sign_out requests.  
If no TP Desktop Connector messages are received, the service returns  
immediately. If a TP Desktop Connector message is received, the service  
calls the appropriate completion routine or presentation procedure and then  
returns (see Com pa q TP Desktop Con n ector for ACMS Client Application  
Programming Guide.  
Note that this call is not used in the forced nonblocking environment. See  
Section 4.13.  
Format  
acmsdi_dispatch_message ( )  
Parameters  
No parameters are specified.  
Return Status  
The status values returned by the acmsdi_dispatch_message service are listed  
in Table 2–5.  
Table 2–5 acmsdi_dispatch_message Return Status Values  
Status  
Description  
ACMSDI_INTERNAL  
ACMSDI_NOMEMORY  
Internal TP Desktop Connector error.  
Insufficient memory.  
(continued on next page)  
TP Desktop Connector Portable API Client Services 2–23  
acmsdi_dispatch_message  
Table 2–5 (Cont.) acmsdi_dispatch_message Return Status Values  
Status  
Description  
ACMSDI_NORMAL  
ACMSDI_SRVDEAD  
Normal successful completion.  
Node name is invalid, or TP Desktop  
Connector gateway is not running on  
the specified node, or the network link  
terminated.  
2–24 TP Desktop Connector Portable API Client Services  
acmsdi_return_pointer  
2.10 acmsdi_return_pointer  
TP Desktop Connector client programs written in Visual Basic use the  
ACMSDI_RETURN_POINTER service to create the workspace array for the  
ACMSDI_CALL_TASK routine. When passing a workspace, the ACMSDI_  
CALL_TASK service expects a data structure with the size and address of each  
workspace. The ACMSDI_RETURN_POINTER service assigns the address of  
a workspace argument to the contents of a pointer address argument. This  
service may be used in the forced nonblocking environment to obtain reference  
pointers to structures such as call_id.  
Format  
acmsdi_return_pointer (structure)  
Parameters  
structure  
Type: lon g in t  
Access: r ea d  
Mechanism: by r efer en ce  
The workspace or other structure for which a pointer is to be obtained.  
Return Status  
The return status value for acmsdi_return_pointer is the address of the  
structure passed as the parameter in the call.  
TP Desktop Connector Portable API Client Services 2–25  
acmsdi_sign_in  
2.11 acmsdi_sign_in  
TP Desktop Connector client programs call this service to sign a user in to a  
ACMS system.  
Format  
acmsdi_sign_in (submitter_node,  
username,  
password,  
[options],  
submitter_id,  
[completion_status],  
[completion_routine],  
[call_context])  
1
Parameters  
submitter_node  
Type: ch a r *  
Access: r ea d  
Mechanism: by r efer en ce  
The node name of the ACMS system where the user is to be signed in.  
Maximum length is 80.  
username  
Type: ch a r *  
Access: r ea d  
Mechanism: by r efer en ce  
The name of the OpenVMS account of the user to be signed in. Maximum  
length is 80.  
password  
Type: ch a r *  
Access: r ea d  
Mechanism: by r efer en ce  
The password of the user to be signed in. Maximum length is 80.  
1
For nonblocking only, see Section 2.3.  
2–26 TP Desktop Connector Portable API Client Services  
acmsdi_sign_in  
options  
Type: ACMSDI_OP TION a r r a y  
Access: r ea d  
Mechanism: by r efer en ce  
Union containing multiple structures and an option variable, the value of  
which defines the type of option being selected (see Section 2.5.1).  
submitter_id  
Type: ACMSDI_SUBMITTER_ID  
Access: w r ite  
Mechanism: by r efer en ce  
A structure into which the acmsdi_sign_in service writes a newly created  
submitter identification. Other services use the submitter identification as  
a handle to identify an active submitter. The ACMSDI_SUBMITTER_ID  
structure is defined in the ACMSDI.H include file.  
completion_status  
Type: in t  
Access: w r ite  
Mechanism: by r efer en ce  
The final status of the service. In the blocking environment, the completion_  
status parameter is set to zero when the service starts successfully.  
When the service completes, completion_status contains the final status. See  
Table 2–6 for a list of return status values.  
completion_routine  
Type: fu n ction a d d r ess  
1
Access: r ea d  
Mechanism: by va lu e  
Address of a function to be called when the nonblocking service completes. The  
completion routine is called by the acmsdi_dispatch_message service when the  
reply is received from the TP Desktop Connector gateway.  
call_context  
Type: void *  
Access: r ea d  
Mechanism: by va lu e  
Optional parameter passed to presentation procedures and completion routines  
to identify the call. Use this parameter to supply application-specific context  
for the call.  
1
For nonblocking only, see Section 2.3. Not applicable to forced nonblocking and will  
cause an error if supplied.  
TP Desktop Connector Portable API Client Services 2–27  
acmsdi_sign_in  
Return Status  
The status values returned by the acmsdi_sign_in service are listed in  
Table 2–6.  
Table 2–6 acmsdi_sign_in Return Status Values  
Status  
Description  
ACMSDI_CALLACTV  
ACMSDI_INSUFPRM  
ACMSDI_INTERNAL  
ACMSDI_INVLOGIN  
ACMSDI_INVOPTION  
ACMSDI_INVPROTOCOL  
Call is active.  
Insufficient parameters.  
Internal TP Desktop Connector error.  
Invalid login attempt.  
Invalid item in options list.  
Mismatch in versions of TP Desktop  
Connector client and gateway software.  
ACMSDI_MIXEDMODE  
All calls on a connection must be either  
blocking or nonblocking.  
ACMSDI_NOACMS  
ACMS system not available.  
ACMSDI_NOCOMPRESS  
ACMSDI_NOMEMORY  
Gateway does not allow compression.  
Insufficient memory to complete  
requests.  
ACMSDI_NORMAL  
ACMSDI_PENDING  
Normal successful completion.  
Successful operation pending  
nonblocking completion. The final  
status is in the completion_status  
parameter.  
ACMSDI_PWDEXPIRED  
ACMSDI_PWDEXPIRING  
Password has expired.  
Password expiring in the number of  
hours specified in options array.  
ACMSDI_SIGNINACTV  
ACMSDI_SIGNOUTACTV  
ACMSDI_SRVDEAD  
Sign-in active.  
Sign-out active.  
Node name is invalid, or TP Desktop  
Connector gateway is not running on  
the specified node, or the network link  
terminated.  
2–28 TP Desktop Connector Portable API Client Services  
acmsdi_sign_out  
2.12 acmsdi_sign_out  
TP Desktop Connector client programs call this service to terminate an active  
session with a ACMS system. To insure that all network links are properly  
shut down, the desktop client program calls the acmsdi_sign_out service before  
terminating.  
Format  
acmsdi_sign_out (submitter_id,  
[completion_status],  
1
[completion_routine],  
[call_context])  
Parameters  
submitter_id  
Type: ACMSDI_SUBMITTER_ID  
Access: r ea d  
Mechanism: by r efer en ce  
The submitter identification returned by the acmsdi_sign_in service.  
completion_status  
Type: in t  
Access: w r ite  
Mechanism: by r efer en ce  
The final status of the service. In the blocking environment, the completion_  
status parameter is set to zero when the service starts successfully.  
When the service completes, completion_status contains the final status. See  
Table 2–7 for a list of the return status values.  
completion_routine  
Type: fu n ction a d d r ess  
1
Access: r ea d  
Mechanism: by va lu e  
Address of a function to be called when the nonblocking service completes. The  
completion routine is called by the acmsdi_dispatch_message service when the  
reply is received from the TP Desktop Connector gateway.  
1
For nonblocking only, see Section 2.3.  
TP Desktop Connector Portable API Client Services 2–29  
acmsdi_sign_out  
call_context  
Type: void *  
Access: r ea d  
Mechanism: by va lu e  
Optional parameter passed to presentation procedures and completion routines  
to identify the call. Use this parameter to supply application-specific context  
for the call.  
Return Status  
The status values returned by the acmsdi_sign_out service are listed in  
Table 2–7.  
Table 2–7 acmsdi_sign_out Return Status Values  
Status  
Description  
ACMSDI_CALLACTV  
Request is invalid while task call is  
active.  
ACMSDI_INSUFPRM  
ACMSDI_INTERNAL  
ACMSDI_INVSUBID  
Insufficient parameters.  
Internal TP Desktop Connector error.  
Invalid or obsolete submitter  
identification.  
ACMSDI_MIXEDMODE  
ACMSDI_NOMEMORY  
All calls on a connection must be either  
blocking or nonblocking.  
Insufficient memory to complete  
requests.  
ACMSDI_NORMAL  
ACMSDI_PENDING  
Normal successful completion.  
Successful operation pending  
nonblocking completion. The final  
status is in the completion_status  
parameter.  
ACMSDI_SIGNINACTV  
Request is invalid while sign-in is  
active.  
(continued on next page)  
2–30 TP Desktop Connector Portable API Client Services  
acmsdi_sign_out  
Table 2–7 (Cont.) acmsdi_sign_out Return Status Values  
Status  
Description  
ACMSDI_SIGNOUTACTV  
Request is invalid while sign-out is  
active.  
ACMSDI_SRVDEAD  
Node name is invalid, or TP Desktop  
Connector gateway is not running on  
the specified node, or the network link  
terminated.  
TP Desktop Connector Portable API Client Services 2–31  
3
Portable API Presentation Procedures  
This chapter describes the interface between the TP Desktop Connector  
gateway and customer-written presentation procedures. It also describes the  
interfaces on portable clients for customer-written action routines to perform  
version checking.  
3.1 Summary of Portable API Presentation Procedures  
Presentation procedures are customer-written routines that the TP Desktop  
Connector gateway calls when an exchange step occurs in a ACMS task with  
either the FORM I/O or REQUEST I/O attribute. Table 3–1 summarizes  
the presentation procedures available in a nonblocking session. These are  
not applicable to a forced nonblocking session. For more information on  
presentation procedures, refer to Com pa q TP Desktop Con n ector for ACMS  
Client Application Programming Guide.  
Table 3–1 Summary of Portable API Presentation Procedures  
Customer-Supplied Procedure  
Description  
acmsdi_disable  
Services a Compaq DECforms disable request,  
which disables a form.  
acmsdi_enable  
Services a DECforms enable request, which enables  
a form.  
acmsdi_read_msg  
Services a TDMS Read exchange, which displays  
the prompt, if any, sent from the ACMS task, and  
acquires the text from the forms message field.  
acmsdi_receive  
Services a DECforms receive request, which sends  
data from the form to the application program.  
(continued on next page)  
Portable API Presentation Procedures 3–1  
Table 3–1 (Cont.) Summary of Portable API Presentation Procedures  
Customer-Supplied Procedure  
Description  
acmsdi_request  
Services a TDMS Request exchange, which displays  
a form and transfers data between a form and the  
application program.  
acmsdi_send  
Services a DECforms send request, which sends  
data from the application program to the form.  
acmsdi_transceive  
acmsdi_write_msg  
Services a DECforms transceive request, which  
combines the actions of a send and a receive.  
Services a TDMS Write exchange, which displays  
the text sent from the forms message field or the  
ACMS task.  
See Com pa q TP Desktop Con n ector for ACMS Client Application  
Programming Guide for a description of sample client presentation procedures.  
3.1.1 Return Status Values Expected from Presentation Procedures  
The presentation procedure routines must return a long integer containing any  
valid OpenVMS status value, including DECforms, TDMS, and application-  
defined values. Return status values for nonblocking presentation procedures  
are returned using the acmsdi_complete_pp routine. The status value is passed  
to the ACMS Application Execution Controller (EXC) as the completion status  
for the exchange step. The EXC attempts to interpret the value as a standard  
OpenVMS status value. Unless the task definition for the exchange step  
specifies CONTINUE ON FAILURE, the EXC cancels the task for an error  
status returned.  
The TP Desktop Connector kit provides include files that specify the return  
status values for DECforms and TDMS: FORMS.H and TDMS.H. If the  
return status values change, you can regenerate the include files with the  
command procedures, MAKE_FORMS_H.COM and MAKE_TDMS_H.COM, in  
the ACMSDI$EXAMPLES directory.  
To handle errors, specify the exception-handler syntax in the task definition.  
To have a single ACMS application support both DECforms terminals and  
graphical desktop systems, code the task definition to check for a DECforms  
error status value.  
3–2 Portable API Presentation Procedures  
3.1.2 ACMSDI_FORM_RECORD Structure and Macro Call  
Defined in the ACMSDI.H file, the ACMSDI_FORM_RECORD type declares  
form records and shadow records passed to and from presentation procedures.  
The code in Example 3–1 defines the ACMSDI_FORM_RECORD type and a  
macro ACMSDI_INIT_FORM_RECORD to initialize the form record structure.  
Example 3–1 Form Record Definition and Initialization Macro  
typedef struct {  
int  
void *data_record;  
int shadow_length;  
data_length;  
/** length of data record **/  
/** pointer to data record **/  
/** length of shadow record **/  
/** pointer to shadow record **/  
void *shadow_record;  
} ACMSDI_FORM_RECORD;  
#define ACMSDI_INIT_FORM_RECORD (record, data, shadow)\  
{\  
record.data_length = sizeof(data);\  
record.data_record = &data;\  
record.shadow_length = sizeof(shadow);\  
record.shadow_record = &shadow;\  
}\  
3.1.3 Prototypes and Code for Presentation Procedures and Version  
Routines  
The ACMSDI.H file contains function prototypes for the presentation  
procedures and action routines that your code supplies. The file PPSTUBS.C  
contains stub modules you can use for linking your application (see Com pa q  
TP Desktop Con n ector for ACMS Client Application Programming Guide).  
3.2 Parameter Memory Allocation  
The caller of a TP Desktop Connector service or 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 the presentation procedures, the desktop  
client program can expect that TP Desktop Connector software allocates  
memory for all the parameters passed in and for all workspaces before it calls  
these procedures.  
Portable API Presentation Procedures 3–3  
3.3 Blocking and Nonblocking Usage  
Like the portable TP Desktop Connector client services, presentation  
procedures can be either blocking or nonblocking. If the desktop client  
program supplies the completion_routine parameter in the acmsdi_call_task  
call, the service behaves in the nonblocking environment (see Section 2.3). In  
a nonblocking environment, presentation procedures must behave in a way  
consistent with nonblocking services.  
3.3.1 Presentation Procedures in a Nonblocking Environment  
When nonblocking services are in use, presentation procedures are written in  
two parts:  
The first part handles the generic presentation procedure and dispatches to  
the application-specific presentation procedure to handle interaction with  
the user.  
The second part uses the acmsdi_complete_pp service to indicate that  
exchange step processing is completed.  
The TP Desktop Connector client services return exchange step data and  
status to the TP Desktop Connector gateway when the desktop client program  
calls the acmsdi_complete_pp service.  
3.3.2 Nonblocking and Blocking Restriction  
All calls using the same desktop client program and TP Desktop Connector  
gateway connection must be either blocking, nonblocking, or forced  
nonblocking. These types of service calls cannot be mixed for a client/server  
pair. If a desktop client program connects to two different TP Desktop  
Connector gateways, it can mix service call types, using blocking calls to  
interact with one gateway and nonblocking calls to interact with the other  
gateway.  
3–4 Portable API Presentation Procedures  
acmsdi_disable  
3.4 acmsdi_disable  
TP Desktop Connector services call this procedure for each active forms session  
for a desktop submitter whenever the TP Desktop Connector client program  
calls acmsdi_sign_out to sign the submitter out of the ACMS system.  
Format  
acmsdi_disable (forms_session,  
call_id,  
call_context)  
Parameters  
forms_session  
Type: ACMSDI_F ORMS_SESSION_ID  
Access: r ea d  
Mechanism: by r efer en ce  
An identification that associates the session with the form specified in the  
acmsdi_enable request (see Section 3.5).  
call_id  
Type: ACMSDI_CALL_ID  
Access: r ea d  
Mechanism: by r efer en ce  
The call identification used to complete the disable call when using nonblocking  
services. See the description of acmsdi_complete_pp (Section 2.8).  
call_context  
Type: void *  
Access: r ea d  
Mechanism: by va lu e  
Application-specific context for the call. This is the same context that was  
passed by the application to the acmsdi_sign_out( ) call.  
Return Status  
The status values returned by the acmsdi_disable procedure are described in  
Section 3.1.1.  
Portable API Presentation Procedures 3–5  
acmsdi_enable  
3.5 acmsdi_enable  
TP Desktop Connector client services call this presentation procedure whenever  
a DECforms ENABLE request is received from the TP Desktop Connector  
gateway on the OpenVMS system.  
Format  
acmsdi_enable (submitter_id,  
forms_session,  
file_specification,  
form_specification,  
forms_print_file,  
forms_language,  
call_id,  
call_context)  
Parameters  
submitter_id  
Type: ACMSDI_SUBMITTER_ID  
Access: r ea d  
Mechanism: by r efer en ce  
The value returned by the acmsdi_sign_in service (see Section 2.11).  
forms_session  
Type: ACMSDI_F ORMS_SESSION_ID  
Access: w r ite  
Mechanism: by r efer en ce  
An identification that associates the session with the submitter identification.  
This is a write parameter that customer-supplied presentation procedures can  
fill. Presentation procedures (acmsdi_send, acmsdi_receive, acmsdi_transceive,  
and acmsdi_disable) can use the forms_session parameter to associate the  
session with the form specified in the enable request. The TP Desktop  
Connector run-time system passes this parameter to subsequent requests to  
specify which form to use.  
3–6 Portable API Presentation Procedures  
acmsdi_enable  
file_specification  
Type: ch a r *  
Access: r ea d  
Mechanism: by r efer en ce  
The form file specification from the ACMS task group definition. Refer to  
Com pa q TP Desktop Con n ector for ACMS Client Application Programming  
Guide for guidelines on specifying the form file specification.  
form_specification  
Type: ch a r *  
Access: r ea d  
Mechanism: by r efer en ce  
The form name specified in the exchange step in the ACMS task definition.  
Refer to Com pa q TP Desktop Con n ector for ACMS Client Application  
Programming Guide for guidelines on specifying the form name.  
forms_print_file  
Type: ch a r *  
Access: r ea d  
Mechanism: by r efer en ce  
The DECforms specification for the user in ACMSUDF.DAT.  
forms_language  
Type: ch a r *  
Access: r ea d  
Mechanism: by r efer en ce  
The DECforms specification for the user in ACMSUDF.DAT.  
call_id  
Type: ACMSDI_CALL_ID  
Access: r ea d  
Mechanism: by r efer en ce  
The call identification returned by the acmsdi_call_task service.  
call_context  
Type: void *  
Access: r ea d  
Mechanism: by va lu e  
Application-specific context for the call. This is the same context that was  
passed by the application to the acmsdi_call_task( ) call.  
Portable API Presentation Procedures 3–7  
acmsdi_enable  
Return Status  
The status values returned by the acmsdi_enable procedure are described in  
Section 3.1.1.  
3–8 Portable API Presentation Procedures  
acmsdi_read_msg  
3.6 acmsdi_read_msg  
TP Desktop Connector client services call this presentation procedure when  
a TDMS Read exchange is received from the TP Desktop Connector gateway  
on the host OpenVMS system. Its function is to display the prompt (if any)  
sent from the ACMS task and then to acquire the text from the forms Message  
Field to be returned to ACMS.  
Format  
acmsdi_read_msg (submitter_id,  
msg_text,  
prompt_text,  
call_id,  
call_context)  
Parameters  
submitter_id  
Type: ACMSDI_SUBMITTER_ID  
Access: r ea d  
Mechanism: by r efer en ce  
The value returned by the acmsdi_sign_in service.  
msg_text  
Type: ch a r  
Access: w r ite  
Mechanism: by r efer en ce  
A buffer into which the presentation procedure will write the text from the  
forms Message Field to be returned to the ACMS task. This is a C-style  
null-terminated string with a maximum length of 132 plus one for the null  
terminator.  
prompt_text  
Type: ch a r  
Access: r ea d  
Mechanism: by r efer en ce  
Text to be displayed as a prompt to the terminal operator. This is a C-style  
null-terminated string with a maximum length of 132 plus one for the null  
terminator. There may be no prompt text to display in which case the length  
will be 0; that is, the null terminator will be in the first position.  
Portable API Presentation Procedures 3–9  
acmsdi_read_msg  
call_id  
Type: ACMSDI_CALL_ID  
Access: r ea d  
Mechanism: by r efer en ce  
The call identification returned by the acmsdi_call_task service which initiated  
the ACMS task associated with this exchange.  
call_context  
Type: void *  
Access: r ea d  
Mechanism: by va lu e  
Application-specific context for the call. This is the same context that was  
passed by the application to the acmsdi_call_task service which initiated the  
ACMS task associated with this exchange.  
Return Status  
This function returns a ps32, defined in ACMSDI.H to be equivalent to a  
signed 32-bit integer. The value must be a valid TDMS status code. Valid  
TDMS statuses are defined in TDMS.H.  
3–10 Portable API Presentation Procedures  
acmsdi_receive  
3.7 acmsdi_receive  
The TP Desktop Connector client services call this presentation procedure  
whenever a DECforms RECEIVE request is received from the TP Desktop  
Connector gateway on the OpenVMS system.  
Format  
acmsdi_receive (forms_session,  
receive_record_identifier,  
receive_record_count,  
receive_control_text,  
receive_control_text_count,  
send_control_text,  
send_control_text_count,  
timeout,  
call_id,  
call_context,  
receive_record)  
Parameters  
forms_session  
Type: ACMSDI_F ORMS_SESSION_ID  
Access: r ea d  
Mechanism: by r efer en ce  
An identification to associate the session with the form specified in the acmsdi_  
enable request (see Section 3.5).  
receive_record_identifier  
Type: ch a r *  
Access: r ea d  
Mechanism: by r efer en ce  
The form record name or record list name specified in the RECEIVE request in  
the ACMS task. Refer to Com pa q TP Desktop Con n ector for ACMS Client  
Application Programming Guide for guidelines on specifying the form name.  
receive_record_count  
Type: lon g in t  
Access: r ea d  
Mechanism: by va lu e  
The number of receive record items sent from the ACMS task.  
Portable API Presentation Procedures 3–11  
acmsdi_receive  
receive_control_text  
Type: ch a r *  
Access: w r ite  
Mechanism: by r efer en ce  
A 25-character string that the customer-supplied request can use to return  
receive control text.  
receive_control_text_count  
Type: lon g in t  
Access: w r ite  
Mechanism: by r efer en ce  
The number of receive control text items that the customer-supplied request  
returns.  
send_control_text  
Type: ch a r *  
Access: r ea d  
Mechanism: by r efer en ce  
Send control text sent from the ACMS task.  
send_control_text_count  
Type: lon g in t  
Access: r ea d  
Mechanism: by va lu e  
The number of send control text items sent from the ACMS task.  
timeout  
Type: sh or t in t  
Access: r ea d  
Mechanism: by va lu e  
A timeout value for user input processing sent from the ACMS task.  
call_id  
Type: ACMSDI_CALL_ID  
Access: r ea d  
Mechanism: by r efer en ce  
The call identification returned by the acmsdi_call_task service.  
call_context  
Type: void *  
Access: r ea d  
Mechanism: by va lu e  
Application-specific context for the call. This is the same context that was  
passed by the application to the acmsdi_call_task( ) call.  
3–12 Portable API Presentation Procedures  
acmsdi_receive  
receive_record  
Type: ACMSDI_F ORM_RECORD a r r a y  
Access: w r ite  
Mechanism: by r efer en ce  
An array of ACMSDI_FORM_RECORD structures pointing to buffers that  
store application data and shadow records from the request (see Section 3.1.2).  
Return Status  
The status values returned by the acmsdi_receive procedure are described in  
Section 3.1.1.  
Portable API Presentation Procedures 3–13  
acmsdi_request  
3.8 acmsdi_request  
TP Desktop Connector client services call this presentation procedure whenever  
a TDMS Request exchange is received from the TP Desktop Connector gateway  
on the OpenVMS system.  
Format  
acmsdi_request (submitter_id,  
request_name,  
workspace_count,  
workspaces,  
call_id,  
call_context)  
Parameters  
submitter_id  
Type: ACMSDI_SUBMITTER_ID  
Access: r ea d  
Mechanism: by r efer en ce  
The value returned by the acmsdi_sign_in service (see Section 2.11).  
request_name  
Type: ch a r *  
Access: r ea d  
Mechanism: by r efer en ce  
The name of the TDMS request specified in the ACMS task.  
workspace_count  
Type: lon g in t  
Access: r ea d  
Mechanism: by va lu e  
The number of workspaces sent from the ACMS task.  
3–14 Portable API Presentation Procedures  
acmsdi_request  
workspaces  
Type: ACMSDI_WORKSPACE a r r a y  
Access: r ea d /w r ite  
Mechanism: by r efer en ce  
The workspace data sent from the ACMS task. One or more optional  
workspace arguments can be sent from the task (see Section 2.4).  
call_id  
Type: ACMSDI_CALL_ID  
Access: r ea d  
Mechanism: by r efer en ce  
The call identification returned by the acmsdi_call_task service.  
call_context  
Type: void *  
Access: r ea d  
Mechanism: by va lu e  
Application-specific context for the call. This is the same context that was  
passed by the application to the acmsdi_call_task( ) call.  
Return Status  
The status values returned by the acmsdi_request procedure are described in  
Section 3.1.1.  
Portable API Presentation Procedures 3–15  
acmsdi_send  
3.9 acmsdi_send  
TP Desktop Connector client services call this presentation procedure whenever  
a DECforms SEND request is received from the TP Desktop Connector gateway  
on the OpenVMS system.  
Format  
acmsdi_send (forms_session,  
send_record_identifier,  
send_record_count,  
receive_control_text,  
receive_control_text_count,  
send_control_text,  
send_control_text_count,  
timeout,  
call_id,  
call_context,  
send_record)  
Parameters  
forms_session  
Type: ACMSDI_F ORMS_SESSION_ID  
Access: r ea d  
Mechanism: by r efer en ce  
An identification that associates the session with the form specified in the  
acmsdi_enable request (see Section 3.5).  
send_record_identifier  
Type: ch a r *  
Access: r ea d  
Mechanism: by r efer en ce  
The form record name or record list name specified in the SEND request in  
the ACMS task. Refer to Com pa q TP Desktop Con n ector for ACMS Client  
Application Programming Guide for guidelines on specifying the form name.  
send_record_count  
Type: lon g in t  
Access: r ea d  
Mechanism: by va lu e  
The number of send record items sent from the ACMS task.  
3–16 Portable API Presentation Procedures  
acmsdi_send  
receive_control_text  
Type: ch a r *  
Access: w r ite  
Mechanism: by r efer en ce  
A 25-character string that the customer-supplied request can use to return  
receive control text.  
receive_control_text_count  
Type: lon g in t  
Access: w r ite  
Mechanism: by r efer en ce  
The number of receive control text items that the customer-supplied request  
returns.  
send_control_text  
Type: ch a r *  
Access: r ea d  
Mechanism: by r efer en ce  
Send control text sent from the ACMS task.  
send_control_text_count  
Type: lon g in t  
Access: r ea d  
Mechanism: by va lu e  
The number of send control text items sent from the ACMS task.  
timeout  
Type: sh or t in t  
Access: r ea d  
Mechanism: by va lu e  
A timeout value for user input processing, sent from the ACMS task.  
call_id  
Type: ACMSDI_CALL_ID  
Access: r ea d  
Mechanism: by r efer en ce  
The call identification returned by the acmsdi_call_task service.  
call_context  
Type: void *  
Access: r ea d  
Mechanism: by va lu e  
Application-specific context for the call. This is the same context that was  
passed by the application to the acmsdi_call_task( ) call.  
Portable API Presentation Procedures 3–17  
acmsdi_send  
send_record  
Type: ACMSDI_F ORM_RECORD a r r a y  
Access: r ea d  
Mechanism: by r efer en ce  
An array of ACMSDI_FORM_RECORD structures pointing to buffers  
containing application data and shadow records sent from the ACMS task  
(see Section 3.1.2).  
Return Status  
The status values returned by the acmsdi_send procedure are described in  
Section 3.1.1.  
3–18 Portable API Presentation Procedures  
acmsdi_transceive  
3.10 acmsdi_transceive  
TP Desktop Connector client services call this presentation procedure whenever  
a DECforms TRANSCEIVE request is received from the TP Desktop Connector  
gateway on the OpenVMS system.  
Format  
acmsdi_transceive (forms_session,  
send_record_identifier,  
send_record_count,  
receive_record_identifier,  
receive_record_count,  
receive_control_text,  
receive_control_text_count,  
send_control_text,  
send_control_text_count,  
timeout,  
call_id,  
call_context,  
send_record,  
receive_record)  
Parameters  
forms_session  
Type: ACMSDI_F ORMS_SESSION_ID  
Access: r ea d  
Mechanism: by r efer en ce  
An identification that associates the session with the form specified in the  
acmsdi_enable request (see Section 3.5).  
send_record_identifier  
Type: ch a r *  
Access: r ea d  
Mechanism: by r efer en ce  
The form record name or record list name specified in the SEND request in  
the ACMS task. Refer to Com pa q TP Desktop Con n ector for ACMS Client  
Application Programming Guide for guidelines on specifying the form name.  
Portable API Presentation Procedures 3–19  
acmsdi_transceive  
send_record_count  
Type: lon g in t  
Access: r ea d  
Mechanism: by va lu e  
The number of send record items sent from the ACMS task.  
receive_record_identifier  
Type: ch a r *  
Access: r ea d  
Mechanism: by r efer en ce  
The form record name or record list name specified in the RECEIVE request in  
the ACMS task. Refer to Com pa q TP Desktop Con n ector for ACMS Client  
Application Programming Guide for guidelines on specifying the form name.  
receive_record_count  
Type: lon g in t  
Access: r ea d  
Mechanism: by va lu e  
The number of receive record items sent from the ACMS task.  
receive_control_text  
Type: ch a r *  
Access: w r ite  
Mechanism: by r efer en ce  
A 25-character string that the customer-supplied request can use to return  
receive control text.  
receive_control_text_count  
Type: lon g in t  
Access: w r ite  
Mechanism: by r efer en ce  
The number of receive control text items that the customer-supplied request  
returns.  
send_control_text  
Type: ch a r *  
Access: r ea d  
Mechanism: by r efer en ce  
Send control text sent from the ACMS task.  
3–20 Portable API Presentation Procedures  
acmsdi_transceive  
send_control_text_count  
Type: lon g in t  
Access: r ea d  
Mechanism: by va lu e  
The number of send control text items sent from the ACMS task.  
timeout  
Type: sh or t in t  
Access: r ea d  
Mechanism: by va lu e  
A timeout value for user input processing, sent from the ACMS task.  
call_id  
Type: ACMSDI_CALL_ID  
Access: r ea d  
Mechanism: by r efer en ce  
The call identification returned by the acmsdi_call_task service.  
call_context  
Type: void *  
Access: r ea d  
Mechanism: by va lu e  
Application-specific context for the call. This is the same context that was  
passed by the application to the acmsdi_call_task( ) call.  
send_record  
Type: ACMSDI_F ORM_RECORD a r r a y  
Access: r ea d  
Mechanism: by r efer en ce  
An array of ACMSDI_FORM_RECORD structures pointing to buffers  
containing application data and shadow records sent from the ACMS task  
(see Section 3.1.2).  
receive_record  
Type: ACMSDI_F ORM_RECORD a r r a y  
Access: w r ite  
Mechanism: by r efer en ce  
An array of ACMSDI_FORM_RECORD structures pointing to buffers to receive  
application data and shadow records from the request (see Section 3.1.2).  
Portable API Presentation Procedures 3–21  
acmsdi_transceive  
Return Status  
The status values returned by the acmsdi_transceive procedure are described  
in Section 3.1.1.  
3–22 Portable API Presentation Procedures  
acmsdi_write_msg  
3.11 acmsdi_write_msg  
TP Desktop Connector client services call this presentation procedure when  
a TDMS Write exchange is received from the TP Desktop Connector gateway  
on the host OpenVMS system. Its function is to display the message text sent  
from the ACMS task in the forms Message Field.  
Format  
acmsdi_write_msg (submitter_id,  
msg_text,  
call_id,  
call_context)  
Parameters  
submitter_id  
Type: ACMSDI_SUBMITTER_ID  
Access: r ea d  
Mechanism: by r efer en ce  
The value returned by the acmsdi_sign_in service.  
msg_text  
Type: ch a r  
Access: r ea d  
Mechanism: by r efer en ce  
Text to be displayed in the forms Message Field. This is a C-style null-  
terminated string with a maximum length of 132 plus one for the null  
terminator.  
Portable API Presentation Procedures 3–23  
acmsdi_write_msg  
call_id  
Type: ACMSDI_CALL_ID  
Access: r ea d  
Mechanism: by r efer en ce  
The call identification returned by the acmsdi_call_task service which initiated  
the ACMS task associated with this exchange.  
call_context  
Type: void *  
Access: r ea d  
Mechanism: by va lu e  
Application-specific context for the call. This is the same context that was  
passed by the application to the acmsdi_call_task service which initiated the  
ACMS task associated with this exchange.  
Return Status  
This function returns a ps32, defined in ACMSDI.H to be equivalent to a  
signed 32-bit integer. The value must be a valid TDMS status code. Valid  
TDMS statuses are defined in TDMS.H.  
3–24 Portable API Presentation Procedures  
acmsdi_check_version  
3.12 Version-Checking Routines  
The following sections describe the version-checking routines. Version checking  
is supported on systems using FORM I/O tasks (see Com pa q TP Desktop  
Con n ector for ACMS Client Application Programming Guide).  
3.12.1 acmsdi_check_version  
TP Desktop Connector client services call this routine whenever they receive  
an ENABLE request from the TP Desktop Connector gateway. The action  
routine can check the version string passed from the acmsdi_get_version  
routine on the submitter node and notify the desktop user of any inconsistency.  
You request version checking during a sign-in (see Com pa q TP Desktop  
Con n ector for ACMS Client Application Programming Guide).  
Format  
acmsdi_check_version (form_file,  
version)  
Parameters  
form_file  
Type: ch a r *  
Access: r ea d  
Mechanism: by r efer en ce  
Specification of a form file or a request library from the ACMS task group  
definition.  
version  
Type: ch a r *  
Access: r ea d  
Mechanism: by r efer en ce  
Twenty-four bytes containing the version number or date supplied by the  
acmsdi_get_version routine on the OpenVMS system.  
Portable API Presentation Procedures 3–25  
acmsdi_check_version  
Return Status  
The TP Desktop Connector service checks the status value returned and  
expects a valid OpenVMS status. If a failure status is returned, the TP  
Desktop Connector run-time system terminates the ENABLE request.  
If the version-checking routine determines that software is not synchronized, it  
does one of the following:  
Returns an OpenVMS failure status that cancels the ENABLE request.  
Sets a flag that causes the acmsdi_enable routine to terminate with a  
failure status.  
3–26 Portable API Presentation Procedures  
acmsdi_get_version  
3.12.2 acmsdi_get_version  
The TP Desktop Connector gateway calls this routine on the OpenVMS system  
whenever it receives an ENABLE request from the EXC. The action routine  
can return a version string that is then passed to the desktop client program,  
allowing a version comparison at the desktop system.  
This service can also be used in a forced nonblocking environment, see  
Section 4.3. On a Windows system, version checking occurs during enable  
processing.  
Format  
acmsdi_get_version (form_file,  
version)  
Parameters  
form_file  
Type: ch a r *  
Access: r ea d  
Mechanism: by r efer en ce  
Form file or request library specification from the ACMS task group definition.  
version  
Type: ch a r *  
Access: w r ite  
Mechanism: by r efer en ce  
Twenty-four bytes in which the routine writes the version number or date  
associated with the specified form file. The version parameter is passed to the  
desktop client program to be checked in the acmsdi_check_version routine.  
Return Status  
Always returns SUCCESS status.  
Portable API Presentation Procedures 3–27  
4
Forced Nonblocking Client Services  
This chapter describes the forced nonblocking interface between the TP  
Desktop Connector gateway and customer-written procedures.  
4.1 Summary of Forced Nonblocking Procedures  
Forced nonblocking client services extend the Portable API to support  
development tools that do not provide for callbacks, data pointers or consistent  
memory locations for data. (Such tools include Visual Basic and others.) You  
create a forced nonblocking session when you specify the ACMSDI_OPTION,  
ACMSDI_OPT_NONBLK, with the acmsdi_sign_in service and do not supply  
a completion address. In this session, all calls are nonblocking. Table 4–1  
summarizes the forced nonblocking calls to the TP Desktop Connector API. For  
more information on forced nonblocking calls, refer to Com pa q TP Desktop  
Con n ector for ACMS Client Application Programming Guide.  
Table 4–1 Summary of Forced Nonblocking Procedures  
Customer-Supplied Procedure  
Description  
acmsdi_complete_call  
Returns the completion status. Can also provide  
the ACMS status message and task argument  
workspaces.  
acmsdi_bind_enable_args  
acmsdi_bind_enable_args  
acmsdi_bind_msg  
Retrieves write-only arguments in an enable  
exchange step request.  
Retrieves write-only arguments in an enable  
exchange step request.  
Sends or acquires the message text in TDMS Read  
or Write exchanges, respectively, or acquires the  
prompt text of a TDMS Read exchange.  
(continued on next page)  
Forced Nonblocking Client Services 4–1  
Table 4–1 (Cont.) Summary of Forced Nonblocking Procedures  
Customer-Supplied Procedure  
Description  
acmsdi_bind_receive_recs  
Services receive and transceive exchange steps,  
which send data from the desktop client to the TP  
Desktop Connector gateway.  
acmsdi_bind_request_args  
acmsdi_bind_request_wksps  
acmsdi_bind_send_args  
acmsdi_bind_send_recs  
Provides the client application with the request  
name and identifies the set of workspaces in a  
TDMS request exchange step.  
Services a TDMS exchange step, which transfers  
data between a desktop client and the TP Desktop  
Connector gateway.  
Provides the client application with the send record  
identifier and identifies the records to be received in  
a send exchange step.  
Services send and transceive exchange steps, which  
send data from the TP Desktop Connector gateway  
to the desktop client.  
acmsdi_bind_session_id  
Sends the forms session identifier to the TP Desktop  
gateway during an enable exchange step.  
acmsdi_bind_transceive_args  
Provides the client application with the send and  
receive record identifiers and identifies the records  
to be passed in a transceive exchange step.  
acmsdi_poll  
Returns the message type of a message from the  
back end and a pointer to the call context from the  
client application.  
4.1.1 ACMSDI_FORM_RECORD_BIND Structure  
Defined in the ACMSDI.H and ACMSDI.BAS files, the  
ACMSDI_FORM_RECORD type declares form records and shadow records  
transferred. The code in Example 4–1 defines the ACMSDI_FORM_RECORD_  
BIND type for the C language.  
4–2 Forced Nonblocking Client Services  
Example 4–1 Form Record Definition  
typedef struct {  
unsigned int  
unsigned int  
void *data_record;  
buffer_len;  
rec_len;  
/** length of caller’s record buffer **/  
/** actual length of the form record **/  
/** pointer to data record **/  
unsigned int  
unsigned int  
shadow_buffer_len; /** length of callers shadow buffer **/  
shadow_rec_len;  
/** actual length of shadow record **/  
/** pointer to shadow record **/  
void *shadow_record;  
} ACMSDI_FORM_RECORD_BIND;  
4.1.2 ACMSDI_WORKSPACE_BIND Structure  
Defined in the ACMSDI.H file, the ACMSDI_WORKSPACE_BIND type  
declares workspaces passed to tasks using the acmsdi_call_task service and  
workspaces passed from tasks to acmsdi_request presentation procedures.  
The code in Example 4–2 defines the ACMSDI_WORKSPACE_BIND type  
structure.  
Example 4–2 Workspace Structure Definition  
typedef struct {  
unsigned int buffer_len;  
unsigned int wksp_len;  
void *data;  
/** length of caller’s buffer **/  
/** actual length of the workspace **/  
/** pointer to workspace **/  
} ACMSDI_WORKSPACE_BIND;  
Forced Nonblocking Client Services 4–3  
acmsdi_complete_call  
4.2 acmsdi_complete_call  
The acmsdi_complete_call service is a required call that obtains completion  
arguments for acsmdi_call_task, acsmdi_sign_in, acmsdi_sign_out, and  
acmsdi_cancel services. When acmsdi_poll detects completion,  
acmsdi_complete_call can obtain the completion status for these services. The  
acmsdi_complete_call can also obtain the ACMS status message and task  
argument workspaces sent from the back end for the acmsdi_call_task service.  
Format  
acmsdi_complete_call (submitter_id,  
completion_status,  
[call_id],  
[status_message],  
[workspaces])  
Parameters  
submitter_id  
Type: ACMSDI_SUBMITTER_ID  
Access: r ea d  
Mechanism: by r efer en ce  
The submitter_id returned by the acmsdi_sign_in service.  
completion_status  
Type: in t  
Access: w r ite  
Mechanism: by r efer en ce  
The final status of the TP Desktop Connector client service. When the service  
completes, the completion_status parameter contains the final status. For the  
list of return status values, see Table 4–2.  
When a task is canceled, the TP Desktop Connector gateway reports a specific  
error, where possible. If the gateway cannot convert a ACMS error to a specific  
TP Desktop Connector status, it returns ACMSDI_TASK_FAILED to the  
desktop client program.  
call_id  
Type: ACMSDI_CALL_ID *  
Access: r ea d  
Mechanism: by r efer en ce  
4–4 Forced Nonblocking Client Services  
acmsdi_complete_call  
A structure defined in the ACMSDI.H include file into which the acmsdi_call_  
task service writes a newly created call identification, a handle used by the  
TP Desktop Connector client services to identify an active call for a submitter.  
This parameter is required when completing an acmsdi_call_task service.  
status_message  
Type: ch a r *  
Access: w r ite  
Mechanism: by r efer en ce  
A buffer to receive the message text associated with the task completion status.  
The message text returned is either the text associated with a TP Desktop  
Connector error or the message text returned from a ACMS application.  
Required length is 80. You use this parameter only for the acmsdi_call_task  
service completion.  
Caution  
If the full space is not allocated, the TP Desktop Connector client  
services write past the end of the allocated string and can cause the  
application to fail. Ensure that the desktop client program allocates  
the required length of space.  
workspaces  
Type: ACMSDI_WORKSPACE or ACMSDI_WORKSPACE_OP T a r r a y  
Access: w r ite  
Mechanism: by r efer en ce  
One or more optional workspaces passed to the application from the back end.  
You need to typecast your array to void *. The workspaces must be specified in  
the same order as they are declared in the task definition, and must match the  
number specified in the workspace_count parameter. If you use the ACMSDI_  
WORKSPACE_OPT type, you must set the call_options parameter to allow  
unidirectional workspaces.  
Because buffers may have been relocated by memory management, workspace  
pointers in the structures must be renewed using the acmsdi_return_pointer  
call just prior to issuing acmsdi_complete_call.  
You use this parameter only for the acmsdi_call_task service completion.  
Forced Nonblocking Client Services 4–5  
acmsdi_complete_call  
Return Status  
The status values returned by the acmsdi_complete_call procedure are  
described in Table 4–2.  
Table 4–2 acmsdi_complete_call Return Status Values  
Status  
Description  
ACMSDI_EXCHACTV  
Request is invalid while exchange step  
processing is active.  
ACMSDI_INSUFPRM  
ACMSDI_INTERNAL  
ACMSDI_INVCALLID  
ACMSDI_INVSUBID  
ACMSDI_MIXEDMODE  
ACMSDI_NORMAL  
Insufficient parameters.  
Internal TP Desktop Connector error.  
Invalid or obsolete call identification.  
Invalid or obsolete submitter identification.  
Not a forced nonblocking session.  
Normal successful completion.  
ACMSDI_WRONG_STATE  
Session is in the wrong state for this call.  
4–6 Forced Nonblocking Client Services  
acmsdi_bind_enable_args  
4.3 acmsdi_bind_enable_args  
The client application can call this service whenever acmsdi_poll returns  
ACMSDI_ENABLE_EXCH from the TP Desktop Connector gateway on the  
OpenVMS system. This service retrieves the write-only arguments passed from  
the TP Desktop Connector client services. This is an optional call.  
Format  
acmsdi_bind_enable_args (submitter_id,  
file_specification,  
form_specification,  
form_version,  
forms_print_file,  
forms_language,  
call_id)  
Parameters  
submitter_id  
Type: ACMSDI_SUBMITTER_ID  
Access: r ea d  
Mechanism: by r efer en ce  
The value returned by the acmsdi_sign_in service (see Section 2.11).  
file_specification  
Type: ch a r *  
Access: w r ite  
Mechanism: by r efer en ce  
The form file specification from the ACMS task group definition. Refer to  
Com pa q TP Desktop Con n ector for ACMS Client Application Programming  
Guide for guidelines on specifying the form file specification.  
form_specification  
Type: ch a r *  
Access: w r ite  
Mechanism: by r efer en ce  
The form name specified in the exchange step in the ACMS task definition.  
Refer to Com pa q TP Desktop Con n ector for ACMS Client Application  
Programming Guide for guidelines on specifying the form name.  
Forced Nonblocking Client Services 4–7  
acmsdi_bind_enable_args  
form_version  
Type: ch a r *  
Access: w r ite  
Mechanism: by r efer en ce  
Twenty-four bytes containing the version number or date supplied by the  
acmsdi_get_version routine on the OpenVMS system. The argument provides  
for version checking by the client application. (The acmsdi_check_version is  
not available in a forced nonblocking session.)  
forms_print_file  
Type: ch a r *  
Access: w r ite  
Mechanism: by r efer en ce  
The DECforms specification for the user in ACMSUDF.DAT.  
forms_language  
Type: ch a r *  
Access: w r ite  
Mechanism: by r efer en ce  
The DECforms specification for the user in ACMSUDF.DAT.  
call_id  
Type: ACMSDI_CALL_ID *  
Access: w r ite  
Mechanism: by r efer en ce  
A pointer to the call identification returned by the acmsdi_call_task service. To  
identify the original task call, compare this pointer with a reference pointer to  
the call identifier obtained by acmsdi_return_pointer.  
Return Status  
The status values returned by the acmsdi_bind_enable_args procedure are  
described in Table 4–3.  
4–8 Forced Nonblocking Client Services  
acmsdi_bind_enable_args  
Table 4–3 acmsdi_bind_enable_args Return Status Values  
Status  
Description  
ACMSDI_INSUFPRM  
ACMSDI_INVSUBID  
ACMSDI_MIXEDMODE  
ACMSDI_NORMAL  
Insufficient parameters.  
Invalid or obsolete submitter identification.  
Not a forced nonblocking session.  
Normal successful completion.  
ACMSDI_WRONG_BIND  
Trying to bind arguments for an exchange that  
is not in progress.  
Forced Nonblocking Client Services 4–9  
acmsdi_bind_msg  
4.4 acmsdi_bind_msg  
The client application can call this service when acmsdi_poll returns ACMSDI_  
TDMS_READ_EXCH (a TDMS Read exchange) or ACMSDI_TDMS_WRITE_  
EXCH (a TDMS Write exchange) from the TP Desktop Connector gateway on  
the host OpenVMS system. It performs one of the following functions:  
acquires the prompt text, if any, associated with a TDMS Read exchange  
sends the message text associated with a TDMS Read exchange.  
acquires the message text associated with a TDMS Write exchange.  
If the prompt or message text is being acquired, the text is truncated when  
the buffer supplied is not large enough to hold the entire text. If the buffer is  
larger than the text being acquired, the text is left-justified in the buffer and  
right-filled with blank characters.  
This is an optional call, that is, you are not required to issue this call.  
However, if you do not issue this call you will not be able to process arguments  
received from the server or to send arguments back to the server.  
Format  
acmsdi_bind_msg (submitter_id,  
direction,  
length,  
text,  
call_id)  
Parameters  
submitter_id  
Type: ACMSDI_SUBMITTER_ID  
Access: r ea d  
Mechanism: by r efer en ce  
The value returned by the acmsdi_sign_in service.  
direction  
Type: sh or t in t  
Access: r ea d  
Mechanism: by va lu e  
The value indicates which direction the text is being sent. A value of 1  
indicates that the prompt text from a TDMS Read exchange or the message  
text from a TDMS Write exchange is being copied into the applications memory  
4–10 Forced Nonblocking Client Services  
acmsdi_bind_msg  
from ACMS. A value of 0 indicates that the message text for a TDMS Read  
exchange is being copied to ACMS from the applications memory.  
length  
Type: sh or t in t  
Access: r ea d  
Mechanism: by va lu e  
The length of the text being sent or the length of the buffer to receive the text;  
specifically one of the following:  
the length of the buffer in the applications memory which is to receive the  
prompt text for a TDMS Read exchange.  
the length of the message text being sent to ACMS for a TDMS Read  
exchange.  
the length of the buffer in the applications memory which is to receive the  
message text for a TDMS Write exchange.  
text  
Type: ch a r  
Access: r ea d /w r ite  
Mechanism: by r efer en ce  
The text string being sent to ACMS or the buffer which is to hold the text  
string being acquired from ACMS.  
call_id  
Type: ACMSDI_CALL_ID *  
Access: w r ite  
Mechanism: by r efer en ce  
Pointer to the call identification returned by the acmsdi_call_task service. To  
identify the original task call, compare this pointer with a reference pointer to  
the call identifier obtained by acmsdi_return_pointer.  
Return Status  
This function returns an int value representing a valid TP Desktop Connector  
status code as defined in ACMSDI.H and described in Table 4–4.  
Forced Nonblocking Client Services 4–11  
acmsdi_bind_msg  
Table 4–4 acmsdi_bind_msg Return Status Values  
Status  
Description  
ACMSDI_INSUFPRM  
ACMSDI_INVSUBID  
ACMSDI_MIXEDMODE  
ACMSDI_NORMAL  
Insufficient parameters.  
Invalid or obsolete submitter identification.  
Not a forced nonblocking session call.  
Normal successful completion.  
ACMSDI_WRONG_BIND  
Trying to bind arguments for an exchange that  
is not in progress.  
4–12 Forced Nonblocking Client Services  
acmsdi_bind_receive_args  
4.5 acmsdi_bind_receive_args  
The client application can call this service whenever an acmsdi_poll returns  
ACMSDI_RECV_EXCH from the TP Desktop Connector gateway on the  
OpenVMS system. This service retrieves the write-only arguments passed from  
the TP Desktop Connector client services. This provides the client application  
with the receive record identifier and identifies the appropriate set of forms  
records to send back to ACMS. See also Section 4.6 for information on calls for  
receive forms records and receive control text. This is an optional call.  
Format  
acmsdi_bind_receive_args (submitter_id,  
forms_session,  
receive_record_identifier,  
receive_record_count,  
timeout,  
call_id)  
Parameters  
submitter_id  
Type: ACMSDI_SUBMITTER_ID  
Access: r ea d  
Mechanism: by r efer en ce  
The submitter_id returned by the acmsdi_sign_in service.  
forms_session  
Type: ACMSDI_F ORMS_SESSION_ID  
Access: w r ite  
Mechanism: by r efer en ce  
An identification to associate the session with the form specified in the acmsdi_  
enable request (see Section 4.11).  
receive_record_identifier  
Type: ch a r *  
Access: w r ite  
Mechanism: by r efer en ce  
The form record name or record list name specified in the RECEIVE request in  
the ACMS task. Refer to Com pa q TP Desktop Con n ector for ACMS Client  
Application Programming Guide for guidelines on specifying the form name.  
Forced Nonblocking Client Services 4–13  
acmsdi_bind_receive_args  
receive_record_count  
Type: lon g in t  
Access: w r ite  
Mechanism: by r efer en ce  
The number of receive record items sent from the ACMS task. The TP Desktop  
Connector writes the receive_record_count into this location.  
timeout  
Type: sh or t in t  
Access: w r ite  
Mechanism: by r efer en ce  
A timeout value for user input processing sent from the ACMS task. TP  
Desktop Connector writes the timeout value into this location.  
call_id  
Type: ACMSDI_CALL_ID *  
Access: w r ite  
Mechanism: by r efer en ce  
A pointer to the call identification returned by the acmsdi_call_task service. To  
identify the original task call, compare this pointer with a reference pointer to  
the call identifier obtained by acmsdi_return_pointer.  
Return Status  
The status values returned by the acmsdi_bind_receive_args procedure are  
described in Table 4–5.  
Table 4–5 acmsdi_bind_receive_args Return Status Values  
Status  
Description  
ACMSDI_INSUFPRM  
ACMSDI_INVSUBID  
ACMSDI_MIXEDMODE  
ACMSDI_NORMAL  
Insufficient parameters.  
Invalid or obsolete submitter identification.  
Not a forced nonblocking session call.  
Normal successful completion.  
ACMSDI_WRONG_BIND  
Trying to bind arguments for an exchange that  
is not in progress.  
4–14 Forced Nonblocking Client Services  
acmsdi_bind_receive_recs  
4.6 acmsdi_bind_receive_recs  
The client application calls this service to send the client applications receive  
forms record data to the TP Desktop Connector gateway on the OpenVMS  
system. Use this service after you have retrieved the exchange step arguments  
that identify the forms records to be sent to the TP Desktop Connector gateway.  
This service can also be used to send receive control text to the TP Desktop  
Connector gateway. This is an optional call.  
Format  
acmsdi_bind_receive_recs (submitter_id,  
receive_control_text_flag,  
receive_record)  
Parameters  
submitter_id  
Type: ACMSDI_SUBMITTER_ID  
Access: r ea d  
Mechanism: by r efer en ce  
The value returned by the acmsdi_sign_in service (see Section 2.11).  
receive_control_text_flag  
Type: sh or t in teger  
Access: r ea d  
Mechanism: by va lu e  
A value of 1 indicates that receive control text is to be sent to the TP Desktop  
Connector gateway. A value of 0 indicates that receive control text is not to be  
sent.  
receive_record  
Type: ACMSDI_F ORM_RECORD_BIND a r r a y  
Access: r ea d  
Mechanism: by r efer en ce  
An array of ACMSDI_FORM_RECORD_BIND structures pointing to buffers  
that store application data and shadow records to be sent to the ACMS  
task, (see Com pa q TP Desktop Con n ector for ACMS Client Application  
Programming Guide). If the send_control_text_flag contains a value of 1, the  
first ACMSDI_FORM_RECORD_BIND structure in the array must point to the  
receive control text buffer. No shadow record is associated with receive control  
text.  
Forced Nonblocking Client Services 4–15  
acmsdi_bind_receive_recs  
Return Status  
The status values returned by the acmsdi_bind_receive_recs service are  
described in Table 4–6.  
Table 4–6 acmsdi_bind_receive_recs Return Status Values  
Status  
Description  
ACMSDI_INSUFPRM  
ACMSDI_INVSUBID  
ACMSDI_MIXEDMODE  
ACMSDI_NORMAL  
Insufficient parameters.  
Invalid or obsolete submitter identification.  
Not a forced nonblocking session.  
Normal successful completion.  
ACMSDI_WRONG_BIND  
Trying to bind arguments for an exchange that  
is not in progress.  
4–16 Forced Nonblocking Client Services  
acmsdi_bind_request_args  
4.7 acmsdi_bind_request_args  
The client application can call this service whenever acmsdi_poll returns  
ACMSDI_REQUEST_EXCH (a TDMS exchange step) from the TP Desktop  
Connector gateway on the OpenVMS system. This service retrieves the write-  
only arguments passed from the TP Desktop Connector client services. This  
provides the client application with the request name and and identifies the  
set of workspaces to be received from and then sent back to ACMS. This is an  
optional call.  
Format  
acmsdi_bind_request_args (submitter_id,  
request_name,  
workspace_count,  
call_id)  
Parameters  
submitter_id  
Type: ACMSDI_SUBMITTER_ID  
Access: r ea d  
Mechanism: by r efer en ce  
The value returned by the acmsdi_sign_in service (see Section 2.11).  
request_name  
Type: ch a r *  
Access: w r ite  
Mechanism: by r efer en ce  
The name of the TDMS request specified in the ACMS task.  
workspace_count  
Type: lon g in t  
Access: w r ite  
Mechanism: by r efer en ce  
The number of workspaces sent from the ACMS task. TP Desktop Connector  
writes this workspace count into this location.  
Forced Nonblocking Client Services 4–17  
acmsdi_bind_request_args  
call_id  
Type: ACMSDI_CALL_ID *  
Access: w r ite  
Mechanism: by r efer en ce  
The call identification returned by the acmsdi_call_task service. To identify  
the original task call, compare this pointer with a reference pointer to the call  
identifier obtained by acmsdi_return_pointer.  
Return Status  
The status values returned by the acmsdi_bind_request_args service are  
described in Table 4–7.  
Table 4–7 acmsdi_bind_request_args Return Status Values  
Status  
Description  
ACMSDI_INSUFPRM  
ACMSDI_INVSUBID  
ACMSDI_MIXEDMODE  
ACMSDI_NORMAL  
Insufficient parameters.  
Invalid or obsolete submitter identification.  
Not a forced nonblocking session.  
Normal successful completion.  
ACMSDI_WRONG_BIND  
Trying to bind arguments for an exchange that  
is not in progress.  
4–18 Forced Nonblocking Client Services  
acmsdi_bind_request_wksps  
4.8 acmsdi_bind_request_wksps  
The client application calls this service to copy request workspace data  
between the client application and the ACMS during a TDMS exchange.  
Use the acmsdi_bind_request_wksps call to copy request workspace data  
from TP Desktop Connector gateway to the client application memory. After  
modification, use this call again to copy the modified contents back to the TP  
Desktop Connector gateway. Use this service after you have retrieved the  
exchange step arguments that identify the workspaces from the TP Desktop  
Connector gateway. This is an optional call.  
Format  
acmsdi_enable (submitter_id,  
direction,  
req_wksp_array)  
Parameters  
submitter_id  
Type: ACMSDI_SUBMITTER_ID  
Access: r ea d  
Mechanism: by r efer en ce  
The value returned by the acmsdi_sign_in service (see Section 2.11).  
direction  
Type: sh or t in t  
Access: r ea d  
Mechanism: by va lu e  
The value indicates which direction the workspaces are being sent. A value of  
1 indicates that the workspaces are being copied into the applications memory  
from ACMS. A value of 0 indicates that the workspaces are being copied to  
ACMS from the applications memory.  
workspaces  
Type: ACMSDI_WORKSPACE_BIND a r r a y  
Access: r ea d /w r ite  
Mechanism: by r efer en ce  
The workspace data sent from the ACMS task. One or more workspace  
arguments can be sent from and returned to the task (see Com pa q TP  
Desktop Con n ector for ACMS Client Application Programming Guide).  
Forced Nonblocking Client Services 4–19  
acmsdi_bind_request_wksps  
Return Status  
The status values returned by the acmsdi_bind_request_wksps service are  
described in Table 4–8.  
Table 4–8 acmsdi_bind_request_wksps Return Status Values  
Status  
Description  
ACMSDI_INSUFPRM  
ACMSDI_INVSUBID  
ACMSDI_MIXEDMODE  
ACMSDI_NORMAL  
Insufficient parameters.  
Invalid or obsolete submitter identification.  
Not a forced nonblocking session.  
Normal successful completion.  
ACMSDI_WRONG_BIND  
Trying to bind arguments for an exchange that  
is not in progress.  
4–20 Forced Nonblocking Client Services  
acmsdi_bind_send_args  
4.9 acmsdi_bind_send_args  
The client application can call this service whenever an acmsdi_poll returns  
ACMSDI_SEND_EXCH from the TP Desktop Connector gateway on the  
OpenVMS system. This service retrieves the write-only arguments passed from  
the TP Desktop Connector client services. This provides the client application  
with the send record identifier and identifies the set of forms records it receives  
from ACMS. See also Section 4.10 for information on calls for send forms  
records and send control text. This is an optional call.  
Format  
acmsdi_bind_send_args (submitter_id,  
forms_session,  
send_record_identifier,  
send_record_count,  
timeout,  
call_id)  
Parameters  
submitter_id  
Type: ACMSDI_SUBMITTER_ID  
Access: r ea d  
Mechanism: by r efer en ce  
The submitter_id returned by the acmsdi_sign_in service.  
forms_session  
Type: ACMSDI_F ORMS_SESSION_ID  
Access: w r ite  
Mechanism: by r efer en ce  
An identification that associates the session with the form specified in the  
acmsdi_enable request (see Section 4.11).  
send_record_identifier  
Type: ch a r *  
Access: w r ite  
Mechanism: by r efer en ce  
The form record name or record list name specified in the SEND request in  
the ACMS task. Refer to Com pa q TP Desktop Con n ector for ACMS Client  
Application Programming Guide for guidelines on specifying the form name.  
Forced Nonblocking Client Services 4–21  
acmsdi_bind_send_args  
send_record_count  
Type: lon g in t  
Access: w r ite  
Mechanism: by r efer en ce  
The number of send record items sent from the ACMS task. TP Desktop  
Connector writes the send_record_count into this location.  
timeout  
Type: sh or t in t  
Access: w r ite  
Mechanism: by r efer en ce  
A timeout value for user input processing, sent from the ACMS task. TP  
Desktop Connector writes the timeout value into this location.  
call_id  
Type: ACMSDI_CALL_ID *  
Access: w r ite  
Mechanism: by r efer en ce  
A pointer to the call identification returned by the acmsdi_call_task service. To  
identify the original task call, compare this pointer with a reference pointer to  
the call identifier obtained by acmsdi_return_pointer.  
Return Status  
The status values returned by the acmsdi_bind_send_args procedure are  
described in Table 4–9.  
Table 4–9 acmsdi_bind_send_args Return Status Values  
Status  
Description  
ACMSDI_INSUFPRM  
ACMSDI_INVSUBID  
ACMSDI_MIXEDMODE  
ACMSDI_NORMAL  
Insufficient parameters.  
Invalid or obsolete submitter identification.  
Not a forced nonblocking session.  
Normal successful completion.  
ACMSDI_WRONG_BIND  
Trying to bind arguments for an exchange that  
is not in progress.  
4–22 Forced Nonblocking Client Services  
acmsdi_bind_send_recs  
4.10 acmsdi_bind_send_recs  
The client application calls this service to retrieve send forms record data from  
the TP Desktop Connector gateway on the OpenVMS system. Use this service  
after you have retrieved the exchange step arguments that identify the forms  
records required from the TP Desktop Connector gateway. This service can also  
be used to retrieve send control text from the TP Desktop Connector gateway.  
This is an optional call.  
Format  
acmsdi_bind_send_recs (submitter_id,  
send_control_text_flag,  
send_record)  
Parameters  
submitter_id  
Type: ACMSDI_SUBMITTER_ID  
Access: r ea d  
Mechanism: by r efer en ce  
The value returned by the acmsdi_sign_in service (see Section 2.11).  
send_control_text_flag  
Type: sh or t in teger  
Access: r ea d  
Mechanism: by va lu e  
A value of 1 indicates that send control text is to be copied from the ACMS  
task. A value of 0 indicates that send control text is not to be copied.  
send_record  
Type: ACMSDI_F ORM_RECORD_BIND a r r a y  
Access: w r ite  
Mechanism: by r efer en ce  
An array of ACMSDI_FORM_RECORD_BIND structures pointing to buffers  
containing application data and shadow records sent from the ACMS task (see  
Com pa q TP Desktop Con n ector for ACMS Client Application Programming  
Guide). If the send_control_text_flag contains a value of 1, the first ACMSDI_  
FORM_RECORD_BIND structure in the array must point to the send control  
text buffer. There is no shadow record associated with send control text.  
Forced Nonblocking Client Services 4–23  
acmsdi_bind_send_recs  
Return Status  
The status values returned by the acmsdi_bind_send_recs service are described  
in Table 4–10.  
Table 4–10 acmsdi_bind_send_recs Return Status Values  
Status  
Description  
ACMSDI_INSUFPRM  
ACMSDI_INVSUBID  
ACMSDI_MIXEDMODE  
ACMSDI_NORMAL  
Insufficient parameters.  
Invalid or obsolete submitter identification.  
Not a forced nonblocking session.  
Normal successful completion.  
ACMSDI_WRONG_BIND  
Trying to bind arguments for an exchange that  
is not in progress.  
4–24 Forced Nonblocking Client Services  
acmsdi_bind_session_id  
4.11 acmsdi_bind_session_id  
You can issue the acmsdi_bind_session_id service to send the forms session ID  
argument to ACMS during an enable exchange step. This is an optional call.  
Format  
acmsdi_bind_session_id (submitter_id,  
forms_session)  
Parameters  
submitter_id  
Type: ACMSDI_SUBMITTER_ID  
Access: r ea d  
Mechanism: by r efer en ce  
The value returned by the acmsdi_sign_in service (see Section 2.11).  
forms_session  
Type: ACMSDI_F ORMS_SESSION_ID  
Access: r ea d  
Mechanism: by r efer en ce  
An identification that associates the session with the submitter identification.  
The user-written application can use the forms_session parameter to associate  
the session with the form specified in the enable request. The TP Desktop  
Connector run-time system passes this parameter to subsequent requests to  
specify which form to use.  
Forced Nonblocking Client Services 4–25  
acmsdi_bind_session_id  
Return Status  
The status values returned by the acmsdi_bind_session_id procedure are  
described in Table 4–11.  
Table 4–11 acmsdi_bind_session_id Return Status Values  
Status  
Description  
ACMSDI_INSUFPRM  
ACMSDI_INVSUBID  
ACMSDI_MIXEDMODE  
ACMSDI_NORMAL  
Insufficient parameters.  
Invalid or obsolete submitter identification.  
Not a forced nonblocking session.  
Normal successful completion.  
ACMSDI_WRONG_BIND  
Trying to bind arguments for an exchange that  
is not in progress.  
4–26 Forced Nonblocking Client Services  
acmsdi_bind_transceive_args  
4.12 acmsdi_bind_transceive_args  
The client application can call this service whenever an acmsdi_poll returns  
ACMSDI_TRCV_EXCH from the TP Desktop Connector gateway on the  
OpenVMS system. This service retrieves the write-only arguments passed from  
the TP Desktop Connector client services. This provides the client application  
with the send and receive record identifiers and identifies the set of forms  
records to be received from and sent to ACMS. See Section 4.6 for information  
on calls for receive forms records and receive control text. See Section 4.10 for  
information on calls for send forms records and send control text. This is an  
optional call.  
Format  
acmsdi_bind_transceive_args submitter_id,  
forms_session,  
send_record_identifier,  
send_record_count,  
receive_record_identifier,  
receive_record_count,  
timeout,  
call_id )  
Parameters  
submitter_id  
Type: ACMSDI_SUBMITTER_ID  
Access: r ea d  
Mechanism: by r efer en ce  
The submitter_id returned by the acmsdi_sign_in service.  
forms_session  
Type: ACMSDI_F ORMS_SESSION_ID  
Access: w r ite  
Mechanism: by r efer en ce  
An identification to associate the session with the form specified in the acmsdi_  
enable request (see Section 4.11).  
Forced Nonblocking Client Services 4–27  
acmsdi_bind_transceive_args  
send_record_identifier  
Type: ch a r *  
Access: w r ite  
Mechanism: by r efer en ce  
The form record name or record list name specified in the SEND request in  
the ACMS task. Refer to Com pa q TP Desktop Con n ector for ACMS Client  
Application Programming Guide for guidelines on specifying the form name.  
send_record_count  
Type: lon g in t  
Access: w r ite  
Mechanism: by r efer en ce  
The number of send record items sent from the ACMS task. TP Desktop  
Connector writes the send_record_count into this location.  
receive_record_identifier  
Type: ch a r *  
Access: w r ite  
Mechanism: by r efer en ce  
The form record name or record list name specified in the RECEIVE request in  
the ACMS task. Refer to Com pa q TP Desktop Con n ector for ACMS Client  
Application Programming Guide for guidelines on specifying the form name.  
receive_record_count  
Type: lon g in t  
Access: w r ite  
Mechanism: by r efer en ce  
The number of receive record items sent from the ACMS task. TP Desktop  
Connector writes the receive_record_count into this location.  
timeout  
Type: sh or t in t  
Access: w r ite  
Mechanism: by r efer en ce  
A timeout value for user input processing, sent from the ACMS task. TP  
Desktop Connector writes the timeout value into this location.  
call_id  
Type: ACMSDI_CALL_ID *  
Access: w r ite  
Mechanism: by r efer en ce  
A pointer to the call identification returned by the acmsdi_call_task service. To  
identify the original task call, compare this pointer with a reference pointer to  
the call identifier obtained by acmsdi_return_pointer.  
4–28 Forced Nonblocking Client Services  
acmsdi_bind_transceive_args  
Return Status  
The status values returned by the acmsdi_bind_transceive_args service are  
described in Table 4–12.  
Table 4–12 acmsdi_bind_transceive_args Return Status Values  
Status  
Description  
ACMSDI_INSUFPRM  
ACMSDI_INVSUBID  
ACMSDI_MIXEDMODE  
ACMSDI_NORMAL  
Insufficient parameters.  
Invalid or obsolete submitter identification.  
Not a forced nonblocking session.  
Normal successful completion.  
ACMSDI_WRONG_BIND  
Trying to bind arguments for an exchange that  
is not in progress.  
Forced Nonblocking Client Services 4–29  
acmsdi_poll  
4.13 acmsdi_poll  
TP Desktop Connector client programs call this nonblocking service to check  
for and process messages sent from a TP Desktop Connector gateway to an  
active submitter in the desktop application. The application must periodically  
call this service in a forced nonblocking environment to check for completion  
of outstanding acmsdi_sign_in, acmsdi_call_task, acmsdi_cancel, and acmsdi_  
sign_out requests. The acmsdi_poll call also checks for the arrival of an  
exchange step from the back end. (For more information, see Com pa q TP  
Desktop Con n ector for ACMS Client Application Programming Guide).  
The acmsdi_poll service returns a pointer to the call context acquired from the  
user application when the just-completed call was issued. Storage for this 32-  
bit integer must exist in the client applications memory. The client application  
can compare this pointer with that returned by the acmsdi_return_pointer  
service to identify the completed call. The call context is identified by matching  
the values.  
Format  
acmsdi_poll (submitter_id,  
call-context)  
Parameters  
submitter_id  
Type: ACMSDI_SUBMITTER_ID  
Access: r ea d  
Mechanism: by r efer en ce  
The submitter_id returned by the acmsdi_sign_in service. The submitter  
identifier is used to identify the submitter for which the call is being  
issued. The acmsdi_poll service passes the submitter identifier as a read-  
only argument. TP Desktop responds with either the message type received  
from the back end for that submitter or a return code indicating that there is  
no message.  
call_context  
Type: void *  
Access: w r ite  
Mechanism: by r efer en ce  
This call writes the pointer to the call context into this optional parameter.  
This context identifies the call message that has arrived from the back end.  
4–30 Forced Nonblocking Client Services  
acmsdi_poll  
For example, if an acmsdi_call_task completion message is sent from the back  
end, this is a pointer to the context supplied on the acmsdi_call_task call.  
This pointer to a structure in the client applications memory is treated as  
a 32-bit integer. To determine the structure being referenced, the client  
application compares this value with the values returned by the acmsdi_  
return_pointer service. Because data can be moved by memory management,  
acmsdi_return_pointer calls must be issued within the same procedure as the  
original call.  
Return Status  
The status values returned by the acmsdi_poll service are listed in Table 4–13.  
Table 4–13 acmsdi_poll Return Status Values  
Status  
Description  
ACMSDI_CANCEL_DONE  
ACMSDI_DONE  
Task cancel call complete.  
Sign-in, sign-out, or task call complete.  
Enable exchange step has arrived.  
ACMSDI_ENABLE_EXCH  
ACMSDI_EXCHACTV  
Request is invalid while exchange step  
processing is active.  
ACMSDI_EXEC  
No message from the back-end  
available; call still executing.  
ACMSDI_INSUFPRM  
ACMSDI_INVSUBID  
Insufficient or conflicting parameters.  
Invalid or obsolete submitter  
identification.  
ACMSDI_INTERNAL  
ACMSDI_MIXEDMODE  
ACMSDI_NOMEMORY  
ACMSDI_READY  
Internal TP Desktop Connector error.  
Not a forced nonblocking session call.  
Insufficient memory.  
No message from the back-end  
available; no call executing.  
ACMSDI_RECV_EXCH  
Receive exchange step has arrived.  
ACMSDI_REQUEST_EXCH  
TDMS Request exchange step has  
arrived.  
ACMSDI_SEND_EXCH  
Send exchange step has arrived.  
(continued on next page)  
Forced Nonblocking Client Services 4–31  
acmsdi_poll  
Table 4–13 (Cont.) acmsdi_poll Return Status Values  
Status  
Description  
ACMSDI_SRVDEAD  
TP Desktop Connector gateway is not  
running on the server node, or the  
network link has been terminated.  
ACMSDI_TDMS_READ_EXCH  
ACMSDI_TDMS_WRITE_EXCH  
ACMSDI_TRCV_EXCH  
TDMS Read exchange has arrived  
TDMS Write exchange has arrived  
Transceive exchange step has arrived.  
4–32 Forced Nonblocking Client Services  
5
System Management Service on OpenVMS  
This chapter describes the system management service available on  
systems running the TP Desktop Connector gateway. The ACMSDI$GET_  
SUBMITTER_INFO service returns information about the status of TP  
Desktop Connector gateway processing on the submitter node.  
System Management Service on OpenVMS 5–1  
ACMSDI$GET_SUBMITTER_INFO  
5.1 ACMSDI$GET_SUBMITTER_INFO  
This service returns information regarding desktop users signed in to the  
Compaq ACMS system. The service reports only those users signed in to the  
TP Desktop Connector gateway running on the same node as the program  
calling the ACMSDI$GET_SUBMITTER_INFO routine. See Com pa q TP  
Desktop Con n ector for ACMS Client Application Programming Guide for  
coding and building guidelines.  
The C-language function prototype and definitions for the item codes are in the  
file ACMSDI.H in the ACMSDI$COMMON directory.  
The ACMSDI$EXAMPLES directory contains a program, SHOW_DESKTOP_  
USERS.EXE, that uses the ACMSDI$GET_SUBMITTER_INFO service, the  
source file (.C), and the build command procedure (.COM). See Com pa q TP  
Desktop Con n ector for ACMS Client Application Programming Guide for  
more information about this program.  
Note  
A program using the ACMSDI$GET_SUBMITTER_INFO service that  
was compiled and linked with TP Desktop Connector Version 3.2 works  
with only TP Desktop Connector Version 3.2.  
Format  
ACMSDI$GET_SUBMITTER_INFO (user_context,  
itmlst,  
[target_submitter_ID],  
[target_desktop_ID],  
[target_username])  
Parameters  
user_context  
Type: lon gw or d (u n sign ed )  
Access: r ea d w r ite  
Mechanism: by r efer en ce  
A context variable acting as a placeholder while the program reports on  
multiple submitters. Before calling ACMSDI$GET_SUBMITTER_INFO  
initially, the program must set the user context variable to zero. On  
5–2 System Management Service on OpenVMS  
ACMSDI$GET_SUBMITTER_INFO  
ACMSDI$GET_SUBMITTER_INFO calls, if the service returns the status  
ACMSDI$_NORMAL, the program does not modify the variable value.  
itmlst  
Type: lon gw or d (u n sign ed )  
Access: r ea d  
Mechanism: by r efer en ce  
Item list describing the information to be reported. Itmlst is the address  
of a list of item descriptors, each of which specifies or controls an item of  
information to be returned. The list of item descriptors is terminated by an  
item code of zero.  
Figure 5–1 shows the item descriptor format.  
Figure 5–1 Submitter Item Descriptor Format  
31  
16  
Item Code  
15  
Buffer Length  
0
Buffer Address  
Return Length Address  
MR-5219-AD  
The valid item codes are described in Table 5–1.  
Table 5–1 Submitter Information Item Codes  
Code Name  
ACMSDI$K_LATEST_MSG_TIME  
Action:  
Returns the OpenVMS absolute date and time at which the  
desktop submitter most recently sent a message to the TP  
Desktop Connector gateway.  
Description:  
The buffer address field of the item descriptor is the address  
of a quadword in which the ACMSDI$GET_SUBMITTER_  
INFO service writes this time.  
(continued on next page)  
System Management Service on OpenVMS 5–3  
ACMSDI$GET_SUBMITTER_INFO  
Table 5–1 (Cont.) Submitter Information Item Codes  
Code Name  
ACMSDI$K_DESKTOP_ID  
Action:  
Returns the desktop gateway submitter identification  
assigned internally by the TP Desktop Connector gateway.  
Description:  
The buffer address field in the item descriptor is the address  
of a two-longword structure. ACMSDI$GET_SUBMITTER_  
INFO writes the desktop gateway submitter number into the  
first field in the target_desktop_ID array, and the instance  
into the second field. These two values make up the complete  
desktop gateway submitter identification.  
ACMSDI$K_NODENAME  
Action:  
Returns the name of the network node from which the desktop  
submitter is signed in to the ACMS system.  
Description:  
The buffer address field in the item descriptor points to a  
user-provided buffer into which ACMSDI$GET_SUBMITTER_  
INFO writes the name. The return length address field of the  
item descriptor points to a word into which ACMSDI$GET_  
SUBMITTER_INFO writes the length of the node name in  
bytes.  
ACMSDI$K_SIGN_IN_TIME  
Action:  
Returns the OpenVMS absolute date and time at which the  
desktop submitter signed in to the TP Desktop Connector  
gateway.  
Description:  
The buffer address field of the item descriptor is the address  
of a quadword in which the ACMSDI$GET_SUBMITTER_  
INFO service writes this time.  
(continued on next page)  
5–4 System Management Service on OpenVMS  
ACMSDI$GET_SUBMITTER_INFO  
Table 5–1 (Cont.) Submitter Information Item Codes  
Code Name  
ACMSDI$K_SUBMITTER_ID  
Action:  
Returns the ACMS submitter_ID of the desktop submitter.  
Description:  
The buffer address field in the item descriptor is the address  
in which the ACMSDI$GET_SUBMITTER_INFO service  
writes the submitter_ID.  
ACMSDI$K_TRANSPORT  
Action:  
Returns an enumerated longword value corresponding to the  
name of the transport used for the submitter sign-in.  
Description:  
The buffer address field of the item descriptor is the address  
of a longword in which ACMSDI$GET_SUBMITTER_INFO  
writes this value.  
ACMSDI$K_USERNAME  
Action:  
Returns the user name under which the desktop submitter is  
signed in.  
Description:  
The buffer address field in the item descriptor points to  
a user-provided buffer into which the ACMSDI$GET_  
SUBMITTER_INFO service writes the user name. The return  
length address field of the item descriptor points to a word  
into which the ACMSDI$GET_SUBMITTER_INFO service  
writes the length of the user name in bytes.  
target_submitter_ID  
Type: u n sign ed Lon g In t  
Access: r ea d  
Mechanism: by r efer en ce  
The ACMS submitter identification as displayed in the ACMS/SHOW USERS  
command.  
target_desktop_ID  
Type: u n sign ed Lon g In t [2]  
Access: r ea d  
Mechanism: by r efer en ce  
The desktop gateway submitter identification, ACMS$DESKTOP_ID, on which  
to report. The first long int contains the desktop gateway submitter number  
and the second long int contains the instance.  
System Management Service on OpenVMS 5–5  
ACMSDI$GET_SUBMITTER_INFO  
target_username  
Type: ch a r a cter str in g d escr ip tor  
Access: r ea d  
Mechanism: by d escr ip tor  
The user name on which to report.  
Return Status  
The status values returned by the ACMSDI$GET_SUBMITTER_INFO service  
are listed in Table 5–2.  
Table 5–2 ACMSDI$GET_SUBMITTER_INFO Return Status Values  
Status  
Description  
ACMSDI$_ILLITEMCODE  
An illegal item code appears in the item list.  
No information is reported.  
ACMSDI$_NOMATCHSUBS  
ACMSDI$_NOMORESUBS  
No matching submitter. No submitter matches  
the selection criteria.  
No more submitters to report. No information  
was reported by this call, because no more  
submitters match the selection criteria. The  
snapshot is consistent with the current set of  
submitters.  
ACMSDI$_NORMAL  
Normal successful completion. Information  
specified by the item list has been reported  
about a matching submitter. Additional  
matching submitters can remain to be  
reported.  
ACMSDI$_OBSINFOREP  
Obsolete information reported. No information  
was returned, because no more submitters  
match the selection criteria. The snapshot  
is not consistent with the current set of  
submitters.  
5–6 System Management Service on OpenVMS  
6
Data Compression Monitor Commands  
This chapter provides a description of the Data Compression Monitor  
commands that you can use to monitor compression activity. You can shorten  
all commands and keywords to the smallest unambiguous abbreviation, which  
is at most three characters.  
See Com pa q TP Desktop Con n ector for ACMS Client Application  
Programming Guide for more information on using the Data Compression  
Monitor.  
Data Compression Monitor Commands 6–1  
EXIT  
6.1 EXIT  
This command exits the Compression Monitor Activity reporting program.  
Format  
EXIT  
6–2 Data Compression Monitor Commands  
HELP  
6.2 HELP  
Displays the help file, SYS$HLP:ACMSDI$DCM_REPORTER_HLP.TXT.  
Format  
HELP  
Data Compression Monitor Commands 6–3  
LIST  
6.3 LIST  
This command generates a report, which you can display on the screen or write  
to a file.  
Format  
LIST [/qualifier]  
Qualifiers  
/APPLICATION=application  
Allows you to select detailed records associated with the application(s)  
specified. The application specification can be an ACMS application name  
or a list of application names. If you specify a list, separate the names with  
a comma and enclose the list within parentheses. The asterisk (*) wild card  
character is permitted in application name specifications. If you do not specify  
/APPLICATION, records for all applications are selected unless you set default  
application(s) with the SET command.  
Specifying /APPLICATION with the LIST command overrides any default  
applications that you previously set. Specifying /APPLICATION=* on the LIST  
command selects records for all applications, overriding any defaults that are  
set.  
/BEFORE[=date-time]  
Selects detailed records that were written before the date and time specified.  
The date-time specification is optional. If you omit it, records written earlier  
than the current date are selected. Specify date and time in the OpenVMS  
standard format dd-mmm-yyyy:hh-mm-ss.  
/DETAILS  
Specifies that the report should contain details of all calls. This is the default,  
unless you specify /SUMMARY in the SET command. Specifying /DETAILS  
with the LIST command overrides SET/SUMMARY.  
/INPUT=file  
Specifies a source file from which records for the report are to be read. If you  
do not specify a source file, the latest version of SYS$ERRORLOG:  
ACMSDI$COMPRESSION.LOG is used, unless you have previously specified  
a default input file using the SET command. To override a default input file  
setting, use /INPUT=* on the LIST command.  
6–4 Data Compression Monitor Commands  
LIST  
/NODE=(node-identifier[,...])  
Selects detailed records associated with task calls originating from the client  
node(s) specified. The node-identifier can be a DECnet node name, TCP/IP  
address, or a list of same. If you specify a list, separate the identifiers with  
commas and enclose the list within parentheses. If you specify a single  
identifier, you do not need the comma and parentheses. The asterisk (*) wild  
card character is permitted in node identifiers. If you do not specify /NODE,  
records for all nodes are selected unless you set default node(s) with the SET  
command.  
Specifying /NODE with the LIST command overrides any default nodes that  
you may have set. Specifying /NODE=* with the LIST command specifies that  
records for all nodes are to be selected, overriding any defaults that you may  
have set.  
/OUTPUT=file  
Directs the report to a file. The file specification must be a valid OpenVMS  
file specification. Displaying the report on the screen is the default, unless you  
specify the /OUTPUT qualifier with the SET command. Specifying /OUTPUT=*  
with the LIST command, displays any reports on the screen, overriding any  
defaults that may be set.  
/SINCE[=date-time]  
Selects detailed records that were written on or after the date and time  
specified. The date-time specification is optional. If you omit it, the records  
written on the current date are selected. Specify the date and time in the  
OpenVMS format, dd-mmm-yyyy:hh:mm:ss.  
/SUMMARY  
Specifies that a summary report, omitting details, be written. The default is  
a detailed report containing all calls be written. You can set your own default  
with the SET command. Summary reports show totals of the uncompressed  
workspace sizes, the compressed workspace sizes, and the number of bytes  
saved by data compression.  
/TASK=task-name  
Selects detailed records associated with ACMS task calls for the task name(s)  
specified, including any exchange steps associated with the task calls. The  
task-name specification can be a valid ACMS task name or a list of task names.  
If you specify a list, separate the names with a comma and enclose the list  
within parentheses. You can use the asterisk (*) wild-card character in the  
task-name specification. If you do not specify the /TASK qualifier, records  
for all tasks are selected, unless you have specified another default with the  
SET command. If you specify /TASK=* with the LIST command, records for  
Data Compression Monitor Commands 6–5  
LIST  
all tasks are selected. If tasks specified are part of more than one ACMS  
application, matching task details for all applications are selected, unless you  
narrow the selection further with the /APPLICATION qualifier.  
/USER=user-identifier  
Selects detailed records associated with ACMS task calls executed for the  
signed-in user session(s) specified. The user-identifier specification can be  
a user identifier or a list of user identifiers. If you specify a list, separate  
the identifiers with a comma and enclose the list within parentheses. The  
asterisk (*) wild card character is permitted in user identifier specifications. If  
/USER is not specified, records for all users are selected, unless default user  
identifier(s) have been selected with the SET command. Specifying /USER on  
the LIST command overrides any default user identifiers that may have been  
set. Specifying /USER=* on the LIST command specifies that records for all  
user sessions are selected, overriding any defaults that may have been set.  
Examples  
/APPLICATION=LARRY  
1.  
Selects records for application LARRY.  
/APPLICATION=(KURT,SARAH)  
2.  
3.  
4.  
5.  
6.  
7.  
Selects records for applications KURT and SARAH.  
/APPLICATION=*DEC*  
Selects records for applications that contain DEC in their names.  
/BEFORE  
Selects records written yesterday and earlier.  
/BEFORE=12-JUN  
Selects records written prior to J une 12th of this year.  
/BEFORE=16:30  
Selects records written prior to today at 4:30 p.m.  
/BEFORE=12-JUN-2002:9:15:30  
Selects records written prior to 30 seconds after 9:15 a.m. on J une 12,  
2002.  
6–6 Data Compression Monitor Commands  
LIST  
/NODE=ALPHA1  
8.  
Selects all records for task calls from node ALPHA1.  
/NODE=(LION,TIGER,PANTHR)  
9.  
Selects all records for task calls from nodes LION, TIGER, and PANTHR.  
/NODE=*CPQ*  
10.  
Selects all records for task calls from nodes that contain CPQ in their  
names.  
/OUTPUT=DAILY_COMPRESSION.REP  
11.  
Directs the report to a file named DAILY_COMPRESSION.REP in the  
current directory.  
/SINCE  
12.  
13.  
14.  
15.  
Selects records written today (after midnight yesterday, or 0:00 today).  
/SINCE=13-JUN  
Selects records written after midnight, J une 12th of the current year.  
/SINCE=11:25  
Selects records written at or after 11:25 this morning.  
/SINCE=12-OCT-2001:8:0:45  
Selects records written at or after 45 seconds after 8 a.m. on October 12,  
2001.  
/TASK=HYACINTH  
16.  
17.  
18.  
Selects records for task calls for ACMS task HYACINTH.  
/TASK=(APRIL,MAY,JUNE)  
Selects records for task calls for ACMS tasks APRIL, MAY, and J UNE.  
/TASK=*DEF  
Selects all records for task calls associated with tasks with names ending  
in DEF.  
Data Compression Monitor Commands 6–7  
LIST  
/USER=MAIN-PLANT  
19.  
20.  
Selects all records for sessions established for user identifier MAIN-PLANT.  
/USER=(SCHMIDT,MASELLA,RAJIV,SWEENEY)  
Selects all records for sessions established for user identifiers SCHMIDT,  
MASELLA, RAJ IV, and SWEENEY.  
/USER=SITE3*  
21.  
Selects all records for sessions established for user identifiers that begin  
with SITE3.  
6–8 Data Compression Monitor Commands  
RENEW  
6.4 RENEW  
This command closes the current log file and opens a new one. The new log file  
is a new version of ACMSDI$COMPRESSION.LOG.  
Format  
RENEW  
Data Compression Monitor Commands 6–9  
SELECT  
6.5 SELECT  
This command selects records from the log file and writes them to a file from  
which you can generate customized reports. If you do not specify a qualifier, all  
records are selected.  
Format  
SELECT file [/qualifier]  
Parameters  
file  
Is a required parameter that specifies the name of the file to which the selected  
records are written.  
Qualifiers  
/APPLICATION=application  
Allows you to select detailed records associated with the application(s)  
specified. The application specification can be an ACMS application name  
or a list of application names. If you specify a list, separate the names with  
a comma and enclose the list within parentheses. The asterisk (*) wild card  
character is permitted in application name specifications. If you do not specify  
/APPLICATION, records for all applications are selected unless you set default  
application(s) with the SET command.  
Specifying /APPLICATION with the SELECT command overrides any default  
applications that you previously set. Specifying /APPLICATION=* on the  
SELECT command selects records for all applications, overriding any defaults  
that are set.  
/BEFORE[=date-time]  
Selects detailed records that were written before the date and time specified.  
The date-time specification is optional. If you omit it, records written earlier  
than the current date are selected. Specify date and time in the OpenVMS  
standard format dd-mmm-yyyy:hh-mm-ss.  
/INPUT=file  
Specifies a source file from which records for the report are to be read. If you  
do not specify a source file, the latest version of SYS$ERRORLOG:  
ACMSDI$COMPRESSION.LOG is used, unless you have previously specified  
6–10 Data Compression Monitor Commands  
SELECT  
a default input file using the SET command. To override a default input file  
setting, use /INPUT=* on the LIST command.  
/NODE=(node-identifier[,...])  
Selects detailed records associated with task calls originating from the client  
node(s) specified. The node-identifier can be a DECnet node name, TCP/IP  
address, or a list of same. If you specify a list, separate the identifiers with  
commas and enclose the list within parentheses. If you specify a single  
identifier, you do not need the comma and parentheses. The asterisk (*) wild  
card character is permitted in node identifiers. If you do not specify /NODE,  
records for all nodes are selected unless you set default node(s) with the SET  
command.  
Specifying /NODE with the SELECT commands overrides any default nodes  
that you may have set. Specifying /NODE=* with the SELECT commands  
specifies that records for all nodes are to be selected, overriding any defaults  
that you may have set.  
/SINCE[=date-time]  
Selects detailed records that were written on or after the date and time  
specified. The date-time specification is optional. If you omit it, the records  
written on the current date are selected. Specify the date and time in the  
OpenVMS format, dd-mmm-yyyy:hh:mm:ss.  
/TASK=task-name  
Selects detailed records associated with ACMS task calls for the task name(s)  
specified, including any exchange steps associated with the task calls. The  
task-name specification can be a valid ACMS task name or a list of task names.  
If you specify a list, separate the names with a comma and enclose the list  
within parentheses. You can use the asterisk (*) wild-card character in the  
task-name specification. If you do not specify the /TASK qualifier, records  
for all tasks are selected, unless you have specified another default with the  
SET command. If you specify /TASK=* with the SELECT command, records  
for all tasks are selected. If tasks specified are part of more than one ACMS  
application, matching task details for all applications are selected, unless you  
narrow the selection further with the /APPLICATION qualifier.  
/USER=user-identifier  
Selects detailed records associated with ACMS task calls executed for the  
signed-in user session(s) specified. The user-identifier specification can be  
a user identifier or a list of user identifiers. If you specify a list, separate  
the identifiers with a comma and enclose the list within parentheses. The  
asterisk (*) wild card character is permitted in user identifier specifications. If  
/USER is not specified, records for all users are selected, unless default user  
Data Compression Monitor Commands 6–11  
SELECT  
identifier(s) have been selected with the SET command. Specifying /USER  
with the SELECT command overrides any default user identifiers that may  
have been set. Specifying /USER=* with the SELECT command specifies that  
records for all user sessions are selected, overriding any defaults that may  
have been set.  
6–12 Data Compression Monitor Commands  
SET  
6.6 SET  
This command sets default values for the LIST and SELECT commands. All  
qualifiers, except /BEFORE and /SINCE, can have a default value. You can  
use the SHOW command to display the current default settings. When you set  
a default, it applies to all reports you request with the LIST command and to  
all records you select with the SELECT command. However, you can override  
these default settings on the command line by specifying certain qualifiers.  
Format  
SET /qualifier  
Qualifiers  
/APPLICATION=application  
Allows you to select detailed records associated with the application(s)  
specified. The application specification can be an ACMS application name  
or a list of application names. If you specify a list, separate the names with  
a comma and enclose the list within parentheses. The asterisk (*) wild card  
character is permitted in application name specifications. If you do not specify  
/APPLICATION, records for all applications are selected.  
/DETAILS  
This default is applicable to the LIST command only. It specifies that the  
report is to contain detailed information for all calls. This is the standard  
default.  
/INPUT=file  
Specifies a source file from which records for the report are to be read. If you  
do not specify a source file, the latest version of SYS$ERRORLOG:  
ACMSDI$COMPRESSION.LOG is used, unless you have previously specified  
a default input file using the SET command. To override a default input file  
setting, use /INPUT=* on the LIST command.  
/NODE=(node-identifier[,...])  
Selects detailed records associated with task calls originating from the client  
node(s) specified. The node-identifier can be a DECnet node name, TCP/IP  
address, or a list of same. If you specify a list, separate the identifiers with  
commas and enclose the list within parentheses. If you specify a single  
identifier, you do not need the comma and parentheses. The asterisk (*) wild  
card character is permitted in node identifiers.  
Data Compression Monitor Commands 6–13  
SET  
/OUTPUT=file  
Directs the report to a file. The file specification must be a valid OpenVMS  
file specification. Displaying the report on the screen is the default, unless you  
specify the /OUTPUT qualifier with the SET command. Specifying /OUTPUT=*  
with the LIST command, displays any reports on the screen, overriding any  
defaults that may be set.  
/SUMMARY  
Specifies that a summary report, omitting details, be written. The default is  
a detailed report containing all calls be written. You can set your own default  
with the SET command. Summary reports show totals of the uncompressed  
workspace sizes, the compressed workspace sizes, and the number of bytes  
saved by data compression.  
/TASK=task-name  
Selects detailed records associated with ACMS task calls for the task name(s)  
specified, including any exchange steps associated with the task calls. The  
task-name specification can be a valid ACMS task name or a list of task  
names. If you specify a list, separate the names with a comma and enclose  
the list within parentheses. You can use the asterisk (*) wild-card character  
in the task-name specification. If you specify /TASK=*, records for all tasks  
are selected. If tasks specified are part of more than one ACMS application,  
matching task details for all applications are selected, unless you narrow the  
selection further with the /APPLICATION qualifier.  
/USER=user-identifier  
Selects detailed records associated with ACMS task calls executed for the  
signed-in user session(s) specified. The user-identifier specification can be a  
user identifier or a list of user identifiers. If you specify a list, separate the  
identifiers with a comma and enclose the list within parentheses. The asterisk  
(*) wild card character is permitted in user identifier specifications. Specifying  
/USER=*, selects records for all users.  
6–14 Data Compression Monitor Commands  
SHOW  
6.7 SHOW  
This command displays the default values for qualifiers of the LIST and  
SELECT commands, which you have set with the SET command. All command  
qualifiers, except /BEFORE and /SINCE, can have a default value. Specifying  
SHOW without any qualifiers displays all defaults.  
Format  
SHOW [/qualifier]  
Qualifiers  
/APPLICATION  
Displays the default for /APPLICATION qualifier.  
/DETAILS  
Displays /DETAILS if /DETAILS is the default; displays /SUMMARY if  
/SUMMARY is the default. /DETAILS and /SUMMARY are mutually exclusive.  
/INPUT  
Displays the default for the /INPUT qualifier.  
/NODE  
Displays the default for the /NODE qualifier.  
/OUTPUT  
Displays the default for the /OUTPUT qualifier.  
/SUMMARY  
Displays /SUMMARY if /SUMMARY is the default; displays /DETAILS if  
/DETAILS is the default. /SUMMARY and /DETAILS are mutually exclusive.  
/TASK  
Displays the default for the /TASK qualifier.  
/USER  
Displays the default for the /USER qualifier.  
Data Compression Monitor Commands 6–15  
A
Compaq ACMS System Status Values  
Table A–1 lists the ACMS system status values and their corresponding  
numeric values as defined in ACMSDI.H and returned in the err2 parameter,  
with corresponding symbols.  
Table A–1 ACMS System Status Values  
Symbol  
Value  
Text  
ACMSDI_NORMAL  
ACMSDI_APPLDEAD  
ACMSDI_CALLACTV  
0
–3001  
–3002  
Normal completion  
ACMS application not started  
Call active — cannot start new  
operation  
ACMSDI_INSUFPRM  
ACMSDI_INTERNAL  
ACMSDI_INVCALLID  
ACMSDI_INVLOGIN  
ACMSDI_INVOPTION  
ACMSDI_INVSUBID  
ACMSDI_MIXEDMODE  
–3003  
–3004  
–3005  
–3006  
–3007  
–3008  
–3009  
Insufficient parameters  
Internal error  
Invalid call identification  
Invalid login attempt  
Invalid submitter option  
Invalid submitter identification  
Using both blocking & non-  
blocking modes  
ACMSDI_NOACMS  
–3010  
–3011  
–3012  
ACMS not active  
ACMSDI_NOMEMORY  
ACMSDI_NOPPACTV  
Low memory resource  
No active presentation  
procedure  
ACMSDI_NOSUCH_APPL  
ACMSDI_NOSUCH_TASK  
ACMSDI_OPR_CANCELLED  
–3013  
–3014  
–3015  
ACMS application not found  
Invalid task code  
Operator canceled ACMS user  
(continued on next page)  
Compaq ACMS System Status Values A–1  
Table A–1 (Cont.) ACMS System Status Values  
Symbol  
Value  
Text  
ACMSDI_PENDING  
ACMSDI_SECCHK  
–3016  
–3017  
–3018  
–3019  
–3020  
Operation started  
ACMS task ACL failure  
Sign-in in process  
ACMSDI_SIGNINACTV  
ACMSDI_SIGNOUTACTV  
ACMSDI_SRVDEAD  
Sign-out in process  
TP Desktop Connector server  
has died  
ACMSDI_TASK_ABORT  
–3021  
–3022  
–3023  
Task has aborted  
ACMSDI_TASK_CANCELLED  
ACMSDI_TASK_SP_DIED  
Task canceled by operator  
Task procedure server process  
has died  
ACMSDI_TASK_FAILED  
ACMSDI_INVPROTOCOL  
–3024  
–3025  
Task failed to complete normally  
Protocol versions of the DDEV  
and the TP Desktop Connector  
server do not match  
ACMSDI_BADNODENAME  
ACMSDI_PWDEXPIRED  
ACMSDI_CANCELACTV  
–3026  
–3027  
–3028  
Invalid node name  
Password has expired  
Client-initiated cancel in  
progress  
ACMSD_EXCHACTV  
–3029  
–3030  
–3031  
User-written presentation  
procedure not completed  
ACMSDI_DISPATCHACTV  
ACMSDI_UNSUPPORTED  
ACMSDI_DISPATCH_  
MESSAGE call in process  
Unsupported option requested  
on acmsdi_sign_in or acmsdi_  
call_task  
ACMSDI_PWDEXPIRING  
–3100  
–3101  
Number of hours returned until  
password expires  
ACMSDI_CALL_CANCELED  
The task was canceled by the  
task submitter  
A–2 Compaq ACMS System Status Values  
Descriptions of client messages and server messages are provided in the  
following files:  
SYS$HELP:ACMSDI$CLIENT_MESSAGES.TXT  
SYS$HELP:ACMSDI$SERVER_MESSAGES.TXT  
Compaq ACMS System Status Values A–3  
Index  
acmsdi_call_task service  
description, 2–13  
acmsdi_cancel service  
A
Access  
description, 2–18  
in documentation format, 1–3  
acmsdi_check_version routine  
interface description, 3–25  
acmsdi_complete_call routine  
description of interface, 4–4  
acmsdi_complete_pp service  
description, 2–21  
acmsdi_disable routine  
description of interface, 3–5  
acmsdi_dispatch_message service  
description, 2–23  
parameter, 1–1  
ACMS$DESKTOP_ID submitter  
description, 5–5  
ACMSDI$GET_SUBMITTER_INFO service  
description, 5–2  
sample program using, 5–2  
acmsdi_bind_enable_args routine  
description of interface, 4–7  
acmsdi_bind_msg routine, 4–10  
acmsdi_bind_receive_args routine  
description of interface, 4–13  
acmsdi_bind_receive_recs routine  
description of interface, 4–15  
acmsdi_bind_request_args routine  
description of interface, 4–17  
acmsdi_bind_request_wksps  
description of interface, 4–19  
acmsdi_bind_send_args routine  
description of interface, 4–21  
acmsdi_bind_send_recs routine  
description of interface, 4–23  
acmsdi_bind_session_id routine  
description of interface, 4–25  
acmsdi_bind_transceive_args routine  
description of interface, 4–27  
ACMSDI_CALL_ID data type, 1–2  
ACMSDI_CALL_OPTIONS data type  
structure, 1–2  
acmsdi_enable routine  
description of interface, 3–6  
ACMSDI_FORMS_SESSION_ID data type  
structure, 1–2  
ACMSDI_FORM_RECORD data type  
definition, 3–3  
structure, 1–2  
ACMSDI_FORM_RECORD_BIND data type  
definition, 4–2  
structure, 1–2  
ACMSDI_FORM_RECORD_BIND structure,  
2–7  
acmsdi_get_version routine  
interface description, 3–27  
ACMSDI_INIT_FORM_RECORD data type  
definition, 3–3  
ACMSDI_INIT_FORM_RECORD_BIND data  
type  
definition, 4–2  
Index–1  
ACMSDI_INIT_WORKSPACE data type  
definition, 2–4  
ACMSDI_OPTION array  
using, 2–11  
acmsdi_transceive routine  
description of interface, 3–19  
ACMSDI_WORKSPACE data type  
definition, 2–4  
ACMSDI_OPTION data type  
structure, 1–2  
ACMSDI_OPT_CHECK_VERSION option  
defined, 2–10  
structure array, 1–2  
ACMSDI_WORKSPACE_BIND data type  
definition, 4–3  
structure, 1–2  
example, 2–27  
acmsdi_write_msg routine, 3–23  
ACMSDI_OPT_COMMID option  
defined, 2–10  
B
example, 2–11  
Blocking service  
ACMSDI_OPT_END_LIST option  
defined, 2–10  
ACMSDI_OPT_FREE_ROUTINE option  
defined, 2–10  
presentation procedure usage, 3–4  
restriction, 2–3, 3–4  
specifying, 2–2  
Brackets  
ACMSDI_OPT_MALLOC_ROUTINE option  
defined, 2–10  
square, in format, 1–1  
ACMSDI_OPT_NONBLK option  
defined, 2–10  
ACMSDI_OPT_PWD_EXPIRING option  
defined, 2–10  
C
Call_id parameter  
specification, 2–21  
Client service  
acmsdi_poll service  
description, 4–30  
summary, 2–1  
Completion routine  
format, 2–3  
acmsdi_read_msg function, 3–9  
acmsdi_receive routine  
description of interface, 3–11  
acmsdi_request routine  
description of interface, 3–14  
acmsdi_return_pointer service  
description, 2–25  
specifying, 2–2  
D
Data compression monitor commands, 6–1  
Data type  
acmsdi_send routine  
description of interface, 3–16  
acmsdi_sign_in service  
description, 2–26  
parameter, 1–2  
acmsdi_sign_out service  
description, 2–29  
ACMSDI_SUBMITTER_ID data type  
structure, 1–2  
E
EXIT command  
description, 6–2  
ACMSDI_SUBMITTER_ID option  
description, 2–27  
ACMSDI_TCPIP_PORT_host_node variable,  
2–11  
Index–2  
F
O
Forced nonblocking services  
described, 4–1  
OpenVMS system  
management service, 5–1  
Options  
specifying, 2–3  
summary, 4–1  
specifying sign-in, 2–27  
Form record  
initialization macro, 3–3  
type definition, 3–3, 4–2  
P
Parameter  
allocating memory, 3–3  
data type, 1–2  
passing mechanism, 1–3  
Portable API client services, 2–1  
Portable API presentation procedure  
summary, 3–1  
G
Gateway  
task cancellation status, 2–15, 4–4  
H
Presentation procedure  
status expected, 3–2  
HELP command  
description, 6–3  
R
Read  
L
LIST command  
description, 6–4  
access method, 1–3  
RENEW command  
description, 6–9  
Return status  
M
description, 1–4  
Management  
service, 5–1  
Mechanism  
S
parameter, 1–1  
parameter passing, 1–3  
Memory  
allocating parameters, 3–3  
Memory allocation, 2–2  
Modify  
SELECT command  
description, 6–10  
Server  
See Gateway  
Service  
client, 2–1  
OpenVMS  
access method, 1–3  
management, 5–1  
summary, 2–1  
Service description  
documentation format, 1–1  
Session  
N
Nonblocking service  
See also Forced nonblocking  
presentation procedure usage, 3–4  
restriction, 2–3, 3–4  
forms identification, 3–6, 4–25  
specifying, 2–2  
Index–3  
Session Environments  
description, 1–4  
SET command  
ID, 5–5  
Target submitter  
ID, 5–5  
description, 6–13  
SHOW command  
description, 6–15  
SHOW_DESKTOP_USERS program  
location, 5–2  
Task  
cancellation status, 2–15, 4–4  
TCP/IP port number, 2–11  
Type  
in documentation format, 1–2  
parameter, 1–1  
Sign-in  
service description, 2–26  
Square brackets  
use in format, 1–1  
Status  
return, 1–4  
Submitter  
V
Version checking  
example, 2–27  
routine  
description, 3–25  
identification  
ACMS, 5–5  
desktop gateway, 5–4  
program for information, 5–2  
Submitter_id  
description, 2–27  
System status values, A–1  
W
Workspace  
defining multiple, 2–5  
initialization macro, 2–4  
relocation by memory management, 4–31  
structure definition, 2–4, 4–3  
Write  
T
access method, 1–3  
Target desktop  
Index–4  

Motorola 6802932J69 User Manual
Meridian America G062 User Manual
Kenwood KDC MP5029 User Manual
JVC CD Receiver KD SX998R User Manual
HTC TOUCH PRO 2 User Manual
Echo Bear Cat 70085 User Manual
DeLonghi Coffeemaker ESAM04350 User Manual
Clarion DXZ856MP User Manual
Addonics Technologies DIAMOND CIPHER DCHD256EU User Manual
ABB REF611_20230308_184814 User Manual