Compaq TP DESKTOP CONNECTOR AAPVNFGTE User Manual
CompaqTPDesktopConnector
forACMS
ClientServicesReferenceManual
Order Number: AA–PVNFG–TE
May 2002
This manual describes the services and commands needed to create and
maintain TP Desktop Connector client programs that use the portable API.
Revision Update Information: This is a revised manual.
Operating System: Compaq OpenVMS VAX
Compaq OpenVMS Alpha
Software Version: Compaq TP Desktop Connector
for ACMS Version 3.2
Compaq Computer Corporation
Houston, Texas
© 2002 Compaq Information Technologies Group, L.P.
Compaq, the Compaq logo, ACMS, ACMS Desktop, ACMSxp, DECnet, the DIGITAL logo,
OpenVMS, and VMScluster are trademarks of Compaq Information Technologies Group, L.P. in
the U.S. and/or other countries.
Microsoft, Windows, Windows NT, and Visual C++ are trademarks of Microsoft Corporation in
the U.S. and/or other countries.
Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems,
Inc., in the U.S. and other countries.
All other product names mentioned herein may be trademarks of their respective companies.
Confidential computer software. Valid license from Compaq required for possession, use, or
copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer
Software Documentation, and Technical Data for Commercial Items are licensed to the U.S.
Government under vendor’s standard commercial license.
Compaq shall not be liable for technical or editorial errors or omissions contained herein. The
information in this document is provided "as is" without warranty of any kind and is subject
to change without notice. The warranties for Compaq products are set forth in the express
limited warranty statements accompanying such products. Nothing herein should be construed
as constituting an additional warranty.
Contents
Preface ..................................................... vii
1 Service Format
1.1 Routine Names . . . ................................... 1–1
1.2 Format . . ........................................... 1–1
1.3 Parameters ......................................... 1–1
1.3.1 Type Entry ....................................... 1–2
1.3.2 Access .......................................... 1–3
1.3.3 Mechanism ....................................... 1–3
1.4 Return Status ....................................... 1–4
1.5 Session Environments ................................. 1–4
2 TP Desktop Connector Portable API Client Services
2.1 Summary of Portable API Client Services .................. 2–1
2.2 Parameter Memory Allocation ........................... 2–2
2.3 Nonblocking Service Usage . . ........................... 2–2
2.3.1 Nonblocking and Blocking Restriction .................. 2–3
2.3.2 Completion Routine Format .......................... 2–3
2.4 Workspace Data Structures . . ........................... 2–4
2.4.1 ACMSDI_WORKSPACE Structure and Initialization
Macro ........................................... 2–4
2.4.2 ACMSDI_WORKSPACE_OPT Structure ................ 2–6
2.4.3 ACMSDI_WORKSPACE_BIND Structure ............... 2–7
2.4.4 ACMSDI_FORM_RECORD_BIND Structure . . . .......... 2–7
2.5 ACMSDI_CALL_OPTION Union Structure ................. 2–8
2.5.1 ACMSDI_OPTION Array . ........................... 2–10
2.6 acmsdi_call_task . . ................................... 2–13
2.7 acmsdi_cancel ....................................... 2–18
2.8 acmsdi_complete_pp ................................... 2–21
2.9 acmsdi_dispatch_message . . . ........................... 2–23
2.10 acmsdi_return_pointer ................................. 2–25
iii
2.11 acmsdi_sign_in ....................................... 2–26
2.12 acmsdi_sign_out ...................................... 2–29
3 Portable API Presentation Procedures
3.1 Summary of Portable API Presentation Procedures ........... 3–1
3.1.1 Return Status Values Expected from Presentation
Procedures ....................................... 3–2
3.1.2 ACMSDI_FORM_RECORD Structure and Macro Call ...... 3–3
3.1.3 Prototypes and Code for Presentation Procedures and
Version Routines . . ................................ 3–3
3.2 Parameter Memory Allocation . . . ........................ 3–3
3.3 Blocking and Nonblocking Usage . ........................ 3–4
3.3.1 Presentation Procedures in a Nonblocking Environment .... 3–4
3.3.2 Nonblocking and Blocking Restriction . . ................ 3–4
3.4 acmsdi_disable ....................................... 3–5
3.5 acmsdi_enable ....................................... 3–6
3.6 acmsdi_read_msg ..................................... 3–9
3.7 acmsdi_receive ....................................... 3–11
3.8 acmsdi_request ...................................... 3–14
3.9 acmsdi_send . ........................................ 3–16
3.10 acmsdi_transceive .................................... 3–19
3.11 acmsdi_write_msg .................................... 3–23
3.12 Version-Checking Routines .............................. 3–25
3.12.1 acmsdi_check_version .............................. 3–25
3.12.2 acmsdi_get_version ................................ 3–27
4 Forced Nonblocking Client Services
4.1 Summary of Forced Nonblocking Procedures ................ 4–1
4.1.1 ACMSDI_FORM_RECORD_BIND Structure ............. 4–2
4.1.2 ACMSDI_WORKSPACE_BIND Structure ............... 4–3
4.2 acmsdi_complete_call . . ................................ 4–4
4.3 acmsdi_bind_enable_args ............................... 4–7
4.4 acmsdi_bind_msg ..................................... 4–10
4.5 acmsdi_bind_receive_args .............................. 4–13
4.6 acmsdi_bind_receive_recs ............................... 4–15
4.7 acmsdi_bind_request_args .............................. 4–17
4.8 acmsdi_bind_request_wksps ............................. 4–19
4.9 acmsdi_bind_send_args ................................ 4–21
4.10 acmsdi_bind_send_recs. ................................ 4–23
4.11 acmsdi_bind_session_id ................................ 4–25
4.12 acmsdi_bind_transceive_args ............................ 4–27
iv
4.13 acmsdi_poll ......................................... 4–30
5 System Management Service on OpenVMS
5.1 ACMSDI$GET_SUBMITTER_INFO . . . ................... 5–2
6 Data Compression Monitor Commands
6.1 EXIT . . . ........................................... 6–2
6.2 HELP . . . ........................................... 6–3
6.3 LIST............................................... 6–4
6.4 RENEW . ........................................... 6–9
6.5 SELECT . ........................................... 6–10
6.6 SET ............................................... 6–13
6.7 SHOW . . ........................................... 6–15
A Compaq ACMS System Status Values
Index
Examples
2–1 Workspace Structure Definition and Initialization ......... 2–5
2–2 Passing Workspaces to a Procedure . ................... 2–5
2–3 ACMSDI_WORKSPACE_OPT Type Definition . . .......... 2–6
2–4 Passing Two Workspaces . ........................... 2–6
2–5 Initializing an Options List .......................... 2–11
2–6 Dynamically Specifying a TCP/IP Port Identifier .......... 2–12
3–1 Form Record Definition and Initialization Macro .......... 3–3
4–1 Form Record Definition . . ........................... 4–3
4–2 Workspace Structure Definition ....................... 4–3
v
Figures
5–1 Submitter Item Descriptor Format .................... 5–3
Tables
1–1 Services Description Parameters ...................... 1–1
1–2 Parameter Data Types .............................. 1–2
1–3 Called Routine Access Methods ....................... 1–3
1–4 Parameter-Passing Mechanisms ...................... 1–4
1–5 Matrix of Services and Environments . . ................ 1–5
2–1 Summary of Portable API Client Services ............... 2–1
2–2 acmsdi_call_task Return Status Values . ................ 2–16
2–3 acmsdi_cancel Return Status Values . . . ................ 2–20
2–4 acmsdi_complete_pp Return Status Values .............. 2–22
2–5 acmsdi_dispatch_message Return Status Values . . . ....... 2–23
2–6 acmsdi_sign_in Return Status Values . . ................ 2–28
2–7 acmsdi_sign_out Return Status Values . ................ 2–30
3–1 Summary of Portable API Presentation Procedures . ....... 3–1
4–1 Summary of Forced Nonblocking Procedures ............. 4–1
4–2 acmsdi_complete_call Return Status Values.............. 4–6
4–3 acmsdi_bind_enable_args Return Status Values . . . ....... 4–9
4–4 acmsdi_bind_msg Return Status Values. ................ 4–12
4–5 acmsdi_bind_receive_args Return Status Values . . . ....... 4–14
4–6 acmsdi_bind_receive_recs Return Status Values . . . ....... 4–16
4–7 acmsdi_bind_request_args Return Status Values . . . ....... 4–18
4–8 acmsdi_bind_request_wksps Return Status Values . ....... 4–20
4–9 acmsdi_bind_send_args Return Status Values ............ 4–22
4–10 acmsdi_bind_send_recs Return Status Values ............ 4–24
4–11 acmsdi_bind_session_id Return Status Values ............ 4–26
4–12 acmsdi_bind_transceive_args Return Status Values. ....... 4–29
4–13 acmsdi_poll Return Status Values ..................... 4–31
5–1 Submitter Information Item Codes .................... 5–3
5–2 ACMSDI$GET_SUBMITTER_INFO Return Status
Values . . ........................................ 5–6
A–1 ACMS System Status Values . ........................ A–1
vi
This manual provides reference information for the TP Desktop Connector
client services, formerly known as the ACMS Desktop Portable API.
Intended Audience
This guide is intended for application programmers, application designers, and
system managers.
Manual Structure
This manual has the following structure:
Chapter Description
Chapter 1 Explains the format of the reference information.
Chapters 2, 3, 4,
and 5
Chapter 6 Lists the data compression monitor commands.
Appendix A Lists the Compaq ACMS system status values that can be returned
Preface
Contain the reference information on TP Desktop Connector client
services, presentation procedures, action routines, and the Compaq
OpenVMS based system management service.
in the err2 parameter.
Related Documents
For information on developing Compaq ACMS applications, refer to the
following manuals:
• Compaq TP Desktop Connector for ACMS Client Application
Programming Guide
Provides information for designing, coding, and implementing a TP Desktop
Connector solution.
vii
• Compaq TP Desktop Connector for ACMS Installation Guide
Provides the steps needed to install a TP Desktop Connector gateway on an
OpenVMS system and the TP Desktop Connector software on the desktop
client system.
• Compaq TP Desktop Connector for ACMS Gateway Management Guide
Contains information about the system management and administration
of the TP Desktop Connector gateway. It also includes information on the
methodology of the use of network transports.
• Compaq TP Desktop Connector for ACMS Getting Started
Provides a high-level discussion and examples of the activities to develop,
install, and run a complete application.
If you are new to programming with ACMS software, Compaq recommends
reading the following books before using the Compaq TP Desktop Connector for
ACMS product:
• Compaq ACMS for OpenVMS Writing Applications
Describes procedures to follow using the Application Development Utility
(ADU).
• Compaq ACMS for OpenVMS Writing Server Procedures
Describes how to write and debug procedures for ACMS applications. Also
supplies reference information for application and system programming
services.
viii
For additional information on ACMS software, refer to the following manuals:
• Compaq ACMS for OpenVMS Introduction
Describes basic concepts and terms concerning the ACMS environment.
• Compaq ACMS for OpenVMS ADU Reference Manual
Describes the details of the syntax for the definitions you create and the
commands you use to build the run-time components.
For information on OpenVMS programming tools, refer to this document:
• Using DECset
Describes the OpenVMS programming environment, provides helpful hints
about conducting a software project, and shows a case study of DECset
tools. Provided with the DECset documentation set.
The Compaq ACMS documentation also describes how you can use the
DECset tools to create an effective development environment.
Conventions
This guide uses the following conventions and symbols:
TP Desktop Connector Refers to the Compaq TP Desktop Connector for ACMS
User Input
$
Return
Ctrl/x
WORD Uppercase text indicates OpenVMS data types, commands,
word In format descriptions, lowercase words indicate parame-
software.
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.
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).
keywords, logical names, and routines or services; C files
and data structures; Microsoft Windows data structures; or
HyperCard data types.
ters, variables, services, or procedures.
ix
italics Italics are used for emphasis and for parameters in text.
[] In format descriptions, square brackets surround a choice of
.
.
.
Windows When used alone, Windows indicates any supported member
Titles of manuals are also italicized.
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.
of the family of Microsoft Windows operating systems.
Where necessary, specific Windows operating systems are
mentioned. For a list of Microsoft Windows operating
systems supported by the TP Desktop Connector product,
see the product’s Software Product Description (SPD).
x
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
1
Service Format
This section contains details about each parameter listed in the format section.
Parameters appear in the order in which they are shown in the format. The
format shown in Table 1–1 describes each parameter.
Table 1–1 Services Description Parameters
Name Description
Type Data type of the parameter
Access Method by which the called routine accesses the parameter
Mechanism Method by which a parameter is passed to the called routine
The parameters section additionally contains a sentence or two describing the
purpose of the parameter.
Service Format 1–1
1.3.1 Type Entry
Table 1–2 lists the C-language data types used in the TP Desktop Connector
services.
Table 1–2 Parameter Data Types
Data Type Description
ACMSDI_CALL_ID Identification returned by the acmsdi_call_task
ACMSDI_FORM_RECORD Structure defined in the ACMSDI.H include file (see
ACMSDI_FORM_RECORD_
BIND
ACMSDI_FORMS_SESSION_ID Structure defined in the ACMSDI.H include file (see
ACMSDI_OPTION Union to specify sign-in options (see Section 2.11)
ACMSDI_CALL_OPTIONS Union to specify call task options
ACMSDI_SUBMITTER_ID Structure defined in the ACMSDI.H include file (see
ACMSDI_WORKSPACE Array of structures defined in the ACMSDI.H
ACMSDI_WORKSPACE_BIND Structure defined in the ACMSDI.H and
ACMSDI_WORKSPACE_OPT Array of structures defined in the ACMSDI.H
char * Array of unsigned 8-bit integers
character string descriptor Address of an OpenVMS string descriptor pointing
function address Address of a function that complies with the
int 32-bit signed integer
long Synonym for long int
long int 32-bit signed integer
service
Section 3.1.2)
Structure defined in the ACMSDI.H and
ACMSDI.BAS include files (see Section 4.1.1)
Section 3.5)
Section 2.11)
include file to pass workspaces between the desktop
system and the TP Desktop Connector gateway (see
Section 2.4)
ACMSDI.BAS include files (see Section 4.1.2)
include file to pass unidirectional workspaces
between the desktop system and the TP Desktop
Connector server
to the character string to be passed
prototype in ACMSDI.H for the completion routine
(continued on next page)
1–2 Service Format
Table 1–2 (Cont.) Parameter Data Types
Data Type Description
longword 32-bit unsigned integer
ptr Longword pointer to data buffer
short Synonym for short int
short int 16-bit signed integer
unsigned long int 32-bit unsigned integer
void * Pointer to object of unknown type
1.3.2 Access
Access describes the way in which the called routine accesses the data specified
by the parameter. The access methods are described in Table 1–3.
Table 1–3 Called Routine Access Methods
Access Method Description
Read Data needed by the called routine to perform its operation is read
Write Data that the called routine returns to the calling routine is written
Modify Data is both read and returned by the called routine; input data
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.
but not returned.
into a location accessible to the calling routine.
specified by the parameter is overwritten.
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
For information on whether the caller or the called routine allocates memory,
see the discussions of the individual platforms.
1.4 Return Status
Each service returns a status value defined as follows:
Platform Value
Windows long int
OpenVMS long int
Tru64 UNIX long int
Only the status codes defined in the related reference sections are valid in the
TP Desktop Connector client services. The definitions for the return status
values are in include files as follows:
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.
Type of Services Include File
Portable client services ACMSDI$COMMON:ACMSDI.H
1.5 Session Environments
Client services can be used in three different session environments, blocking,
nonblocking, and forced nonblocking. In a blocking environment, service
routines are completed in one procedure. In a nonblocking environment,
service routines return control to the desktop client program as soon as a
request is sent and then call the appropriate completion routine when the
request is completed or call the appropriate presentation procedure when an
exchange step is detected.
1–4 Service Format
In a forced nonblocking environment, service routines provide a method of
polling that is used to determine the type of message sent from the back-end
server. This message type may then be used to determine the appropriate
action (for example, process the call completion or exchange step). The forced
nonblocking software provides additional routines to access call completion and
exchange step arguments. These session environments are explained in more
depth in Chapter 2 and in Compaq TP Desktop Connector for ACMS Client
Application Programming Guide.
Table 1–5 lists the services and indicates the session environments in which
you can use each call.
Table 1–5 Matrix of Services and Environments
Service Availability within Environment
Blocking Nonblocking Forced Nonblocking
acmsdi_call_task
See description in Section 2.6
acmsdi_cancel
See description in Section 2.7
acmsdi_complete_pp
See description in Section 2.8
acmsdi_dispatch_message
See description in Section 2.9
acmsdi_return_pointer
See description in Section 2.10
acmsdi_sign_in
See description in Section 2.11
acmsdi_sign_out
See description in Section 2.12
acmsdi_poll
See description in Section 4.13
acmsdi_complete_call
See description in Section 4.2
acmsdi_bind_enable_args
See description in Section 4.3
acmsdi_bind_send_args
See description in Section 4.9
yes yes yes
- yes yes
- yes yes
- yes -
yes - yes
yes yes yes
yes yes yes
- - yes
- - yes
- - yes
- - yes
(continued on next page)
Service Format 1–5
Table 1–5 (Cont.) Matrix of Services and Environments
Service Availability within Environment
Blocking Nonblocking Forced Nonblocking
acmsdi_bind_receive_args
See description in Section 4.5
acmsdi_bind_transceive_args
See description in Section 4.12
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
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
- - yes
- - yes
- - yes
- - yes
- - yes
- - yes
- - yes
- - yes
- yes -
- yes -
- yes -
- yes -
- yes -
- yes -
(continued on next page)
1–6 Service Format
Table 1–5 (Cont.) Matrix of Services and Environments
Service Availability within Environment
Blocking Nonblocking Forced Nonblocking
Callbacks
acmsdi_transceive
See description in Section 3.10
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 -
- yes -
- yes -
- yes yes
Service Format 1–7
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
2
acmsdi_call_task Sends a request to the TP Desktop Connector gateway
acmsdi_cancel Used by nonblocking services only. Called by a desktop
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 customerwritten generic presentation procedures in the desktop
client program.
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
acmsdi_dispatch_
message
acmsdi_return_pointer Used by client programs written in Microsoft Visual Basic
acmsdi_sign_in Requests the TP Desktop Connector gateway to sign a user
acmsdi_sign_out Requests the TP Desktop Connector gateway to sign a
from a presentation procedure request to the TP Desktop
Connector gateway.
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.
to create the workspace array for ACMS_CALL_TASK.
Also used in the forced nonblocking environment to obtain
reference pointers.
running a desktop client program in to a ACMS system.
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 Compaq TP Desktop Connector 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: read
Mechanism: by value
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 **/
void *data; /** pointer to workspace **/
} 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 */
#define ACMSDI_ACCESS_WRITE ’2’ /* write-only access */
#define ACMSDI_ACCESS_MODIFY ’3’ /* modify (read and write) */
.
.
.
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;
2–6 TP Desktop Connector Portable API Client Services
(continued on next page)
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; /* length of caller’s buffer */
unsigned int wksp_len; /* 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; /* length of caller’s record buffer */
unsigned int rec_len; /* actual length of the form record */
void *data_record;
unsigned int shadow_buffer_len; /* length of caller’s shadow buffer */
unsigned int shadow_rec_len; /* 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
ACMSDI_CALL_OPT_ENABLE Pointer to enable function
ACMSDI_CALL_OPT_DISABLE Pointer to disable function
ACMSDI_CALL_OPT_SEND Pointer to send function
ACMSDI_CALL_OPT_RECEIVE Pointer to receive function
ACMSDI_CALL_OPT_TDMS_READ Pointer to TDMS read function
ACMSDI_CALL_OPT_TDMS_WRITE Pointer to TDMS write function
ACMSDI_CALL_OPT_TRANSCEIVE Pointer to transceive function
ACMSDI_CALL_OPT_REQUEST Pointer to TDMS request function
ACMSDI_CALL_OPT_CHECK_VERSION Version checking routine
ACMSDI_CALL_OPT_PASS_TID TID of distributed transaction
ACMSDI_CALL_OPT_COMPRESS_WKSPS Activate workspace compression
optimization
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
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
Caution
ACMSDI_OPT_CHECK_VERSION Enables version checking
ACMSDI_OPT_COMMID Supplies communications device id or
ACMSDI_OPT_END_LIST Ends options list
ACMSDI_OPT_FREE_ROUTINE Enables user-defined memory deallocation
ACMSDI_OPT_MALLOC_ROUTINE Enables user-defined memory allocation
ACMSDI_OPT_NONBLK Enables a forced nonblocking session
ACMSDI_OPT_PWD_EXPIRING Enables checking for passwords that are
2–10 TP Desktop Connector Portable API Client Services
TCP/IP comm port
about to expire
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
Loading...