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

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. Conﬁdential 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

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 Deﬁnition and Initialization ......... 2–5

2–2 Passing Workspaces to a Procedure . ................... 2–5

2–3 ACMSDI_WORKSPACE_OPT Type Deﬁnition . . .......... 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 Identiﬁer .......... 2–12

3–1 Form Record Deﬁnition and Initialization Macro .......... 3–3

4–1 Form Record Deﬁnition . . ........................... 4–3

4–2 Workspace Structure Deﬁnition ....................... 4–3

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

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 deﬁnitions 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 speciﬁed key (indicated here by x).

keywords, logical names, and routines or services; C ﬁles and data structures; Microsoft Windows data structures; or HyperCard data types.

ters, variables, services, or procedures.

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, speciﬁc 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).

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 ﬁle ACMSDI.H in the ACMSDI$COMMON directory.

Square brackets ([]) indicate optional parameters in the call.

1.3 Parameters

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 Identiﬁcation returned by the acmsdi_call_task

ACMSDI_FORM_RECORD Structure deﬁned in the ACMSDI.H include ﬁle (see

ACMSDI_FORM_RECORD_ BIND

ACMSDI_FORMS_SESSION_ID Structure deﬁned in the ACMSDI.H include ﬁle (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 deﬁned in the ACMSDI.H include ﬁle (see

ACMSDI_WORKSPACE Array of structures deﬁned in the ACMSDI.H

ACMSDI_WORKSPACE_BIND Structure deﬁned in the ACMSDI.H and

ACMSDI_WORKSPACE_OPT Array of structures deﬁned 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 deﬁned in the ACMSDI.H and

ACMSDI.BAS include ﬁles (see Section 4.1.1)

Section 3.5)

Section 2.11)

include ﬁle to pass workspaces between the desktop system and the TP Desktop Connector gateway (see Section 2.4)

ACMSDI.BAS include ﬁles (see Section 4.1.2)

include ﬁle 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 speciﬁed 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 speciﬁes 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.

speciﬁed 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 deﬁned as follows:

Platform Value

Windows long int OpenVMS long int Tru64 UNIX long int

Only the status codes deﬁned in the related reference sections are valid in the TP Desktop Connector client services. The deﬁnitions for the return status values are in include ﬁles 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

(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 -

(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

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

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 ﬁeld.

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 ﬁnal 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-speciﬁc context to the completion routine. If speciﬁed 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

Deﬁned in the ACMSDI.H ﬁle, 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 deﬁnes 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 Deﬁnition 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 deﬁned with two elements of type ACMSDI_ WORKSPACE. The structure deﬁnitions control_wksp and employee_record deﬁne 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 ﬁle contains the deﬁnition 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 ﬂag to indicate unidirectional workspaces can use this structure. Example 2–3 shows the ACMSDI_WORKSPACE_OPT type deﬁnition and the deﬁnition of a macro to initialize the workspace structure.

Example 2–3 ACMSDI_WORKSPACE_OPT Type Deﬁnition

#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 speciﬁes the sizes of workspaces during acmsdi_bind_request_wksps operations. Like the ACMSDI_FORM_RECORD_BIND structure, the ACMSDI_WORKSPACE_BIND structure contains a ﬁeld 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 ﬁlled.

The following example shows the C language deﬁnition of this structure as it appears in the acmsdi.h ﬁle:

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 speciﬁes 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 ﬁeld, 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 ﬁt the buffer. If the buffer size is too large, the buffer is not completely ﬁlled.

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 ﬁrst one in the array of such structures passed on the call.

• After the call completes, the record length ﬁeld (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 deﬁnition of this structure as it appears in the acmsdi.h ﬁle:

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 trafﬁc on the call to the acmsdi_call_task client service. The include ﬁle ACMSDI.H contains the deﬁnition 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 deﬁned in the ACMSDI.H include ﬁle:

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 deﬁnition together to optimize unidirectional workspace trafﬁc. 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 ﬁle ACMSDI.H contains the deﬁnition for the ACMSDI_OPTION array.

The ACMSDI_OPTION array is a union containing multiple structures and an option variable, the value of which deﬁnes the type of option being selected. Specify the values for the option variable using the following constants deﬁned in the include ﬁle 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-deﬁned memory deallocation ACMSDI_OPT_MALLOC_ROUTINE Enables user-deﬁned 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-deﬁned 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 deﬁned, the option speciﬁed on the acmsdi_sign_in call takes precedence. If neither the environmental variable nor the sign-in option is speciﬁed, 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 Identiﬁer

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

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], [call_context])

acmsdi_call_task

Parameters

submitter_id

Type: ACMSDI_SUBMITTER_ID Access: read Mechanism: by reference The submitter_id returned by the acmsdi_sign_in service.

call_options

Type: ACMSDI_CALL_OPTION Access: read Mechanism: by reference An array of ACMSDI_CALL_OPTION elements that either enables unidirectional workspace optimization or deﬁnes presentation procedure addresses. The include ﬁle ACMSDI.H contains the deﬁnition 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.

For nonblocking only, see Section 2.3.

TP Desktop Connector Portable API Client Services 2–13

acmsdi_call_task

task_name

Type: char * Access: read Mechanism: by reference The name of the task to execute. Maximum length is 31.

application_name

Type: char * Access: read Mechanism: by reference The speciﬁcation of a ACMS application in which the task resides. The application name must be a valid application speciﬁcation on the submitter node. It can take the form NODE::APPLICATION, or can be speciﬁed using a logical name that is translated by the ACMS Central Controller (ACC) on the submitter node. Maximum length is 80.

selection_string

Type: char * Access: read Mechanism: by reference Used by the desktop client program to pass additional information to the task. Maximum length is 256.

status_message

Type: char * Access: write Mechanism: by reference 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: long int Access: read Mechanism: by value The decimal number of workspaces being passed to the task.

workspaces

Type: ACMSDI_WORKSPACE or ACMSDI_WORKSPACE_OPT array Access: read/write Mechanism: by reference One or more optional workspaces to be passed to the task. You need to typecast your array to void *. The workspaces must be speciﬁed in the same order as they are declared in the task deﬁnition, and must match the number speciﬁed 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: write Mechanism: by reference A structure deﬁned in the ACMSDI.H include ﬁle into which the acmsdi_call_ task service writes a newly created call identiﬁcation, a handle used by the TP Desktop Connector client services to identify an active call for a submitter.

completion_status

Type: int Access: write Mechanism: by reference The ﬁnal 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 ﬁnal status. See Table 2–2 for the list of return status values.

When a task is canceled, the TP Desktop Connector gateway reports a speciﬁc error, where possible. If the gateway cannot convert a ACMS error to a speciﬁc 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: function address Access: read Mechanism: by value Address of a function to be called when the service completes. The completion_ routine is called by the acmsdi_dispatch_message service when the Task" message is received from the TP Desktop Connector gateway.

call_context

Type: void * Access: read Mechanism: by value Optional parameter passed to presentation procedures and completion routines to identify the call. Use this parameter to supply an application-speciﬁc 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 Application stopped unexpectedly. ACMSDI_CALLACTV Call is already active. ACMSDI_INSUFPRM Insufﬁcient parameters. ACMSDI_INTERNAL Internal TP Desktop Connector error. ACMSDI_INVOPTION Invalid item in options list. ACMSDI_INVSUBID Invalid or obsolete submitter identiﬁcation. ACMSDI_MIXEDMODE All calls on a connection must be either

ACMSDI_NOMEMORY Insufﬁcient memory to complete requests. ACMSDI_NORMAL Normal successful completion. ACMSDI_NOSUCH_APPL Application not found.

"End of

blocking or nonblocking.

(continued on next page)

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 ﬁnal status is in the

completion status parameter. ACMSDI_SECCHK Task security check failed. ACMSDI_SIGNINACTV Request is invalid while the sign-in is active. ACMSDI_SIGNOUTACTV Request is invalid while the sign-out is active. ACMSDI_SRVDEAD Node name is invalid, or TP Desktop

Connector gateway is not running on the

speciﬁed node, or the network link terminated. ACMSDI_TASK_ABORT Task completed abnormally. ACMSDI_TASK_CANCELLED Task was canceled. ACMSDI_TASK_FAILED Task failed during execution. ACMSDI_TASK_SP_DIED 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, [call_context])

Parameters

submitter_id

Type: ACMSDI_SUBMITTER_ID Access: read Mechanism: by reference The submitter_id for the session associated with the task that is being canceled.

call_id

Type: ACMSDI_CALL_ID Access: read Mechanism: by reference The call_id for the task that is being canceled, which was passed back on the acmsdi_call_task service.

cancel_reason

Type: long int Access: read Mechanism: by value 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".

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: long int Access: write Mechanism: by reference Optional parameter to contain the ﬁnal 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: function address Access: read Mechanism: by value 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: read Mechanism: by value Optional parameter that is passed to the completion_routine to identify the call. You can use this to supply application-speciﬁc 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.

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 Cancel already in progress. ACMSDI_EXCHACTV Service cannot be called from presentation

ACMSDI_INSUFPRM Insufﬁcient parameters. ACMSDI_INTERNAL Internal ACMS error. ACMSDI_INVCALLID Invalid or obsolete call identiﬁcation. ACMSDI_INVSUBID Invalid or obsolete submitter identiﬁcation. ACMSDI_NOMEMORY Insufﬁcient memory to complete requests. ACMSDI_NORMAL Normal successful completion. ACMSDI_PENDING Successful operation pending nonblocking

ACMSDISIGNINACTV Request is invalid while the sign-in is active. ACMSDISIGNOUTACTV Request is invalid while sign-out is active. ACMSDI_SRVDEAD Node name is invalid, or the TP Desktop

procedure.

completion. The ﬁnal status is in the completion status parameter.

Connector gateway is not running on the speciﬁed node.

2–20 TP Desktop Connector Portable API Client Services

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 Compaq TP Desktop Connector for ACMS Client Application Programming Guide.

Format

acmsdi_complete_pp (call_id,

pp_status)

Parameters

call_id

Type: ACMSDI_CALL_ID Access: read Mechanism: by reference The call_id parameter is passed back on the acmsdi_call_task service.

acmsdi_complete_pp

pp_status

Type: long int Access: read Mechanism: by value 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 Insufﬁcient parameters. ACMSDI_INTERNAL Internal TP Desktop Connector error. ACMSDI_INVCALLID Invalid or obsolete call identiﬁcation. ACMSDI_INVSUBID Invalid or obsolete submitter identiﬁcation. ACMSDI_NOMEMORY Insufﬁcient memory to complete requests. ACMSDI_NOPPACTV No presentation procedure active for this call. ACMSDI_NORMAL Normal successful completion. ACMSDI_SRVDEAD Node name is invalid, or the TP Desktop

Connector gateway is not running on the speciﬁed node, or the network link terminated.

2–22 TP Desktop Connector Portable API Client Services

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 Compaq TP Desktop Connector 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

acmsdi_dispatch_message

No parameters are speciﬁed.

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 Internal TP Desktop Connector error. ACMSDI_NOMEMORY Insufﬁcient 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 Normal successful completion. ACMSDI_SRVDEAD Node name is invalid, or TP Desktop

Connector gateway is not running on the speciﬁed node, or the network link terminated.

2–24 TP Desktop Connector Portable API Client Services

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: long int Access: read Mechanism: by reference The workspace or other structure for which a pointer is to be obtained.

acmsdi_return_pointer

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])

Parameters

submitter_node

Type: char * Access: read Mechanism: by reference The node name of the ACMS system where the user is to be signed in. Maximum length is 80.

username

Type: char * Access: read Mechanism: by reference The name of the OpenVMS account of the user to be signed in. Maximum length is 80.

password

Type: char * Access: read Mechanism: by reference The password of the user to be signed in. Maximum length is 80.

For nonblocking only, see Section 2.3.

2–26 TP Desktop Connector Portable API Client Services

acmsdi_sign_in

options

Type: ACMSDI_OPTION array Access: read Mechanism: by reference Union containing multiple structures and an option variable, the value of which deﬁnes the type of option being selected (see Section 2.5.1).

submitter_id

Type: ACMSDI_SUBMITTER_ID Access: write Mechanism: by reference A structure into which the acmsdi_sign_in service writes a newly created submitter identiﬁcation. Other services use the submitter identiﬁcation as a handle to identify an active submitter. The ACMSDI_SUBMITTER_ID structure is deﬁned in the ACMSDI.H include ﬁle.

completion_status

Type: int Access: write Mechanism: by reference The ﬁnal 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 ﬁnal status. See Table 2–6 for a list of return status values.

completion_routine

Type: function address

Access: read Mechanism: by value 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: read Mechanism: by value Optional parameter passed to presentation procedures and completion routines to identify the call. Use this parameter to supply application-speciﬁc context for the call.

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 Call is active. ACMSDI_INSUFPRM Insufﬁcient parameters. ACMSDI_INTERNAL Internal TP Desktop Connector error. ACMSDI_INVLOGIN Invalid login attempt. ACMSDI_INVOPTION Invalid item in options list. ACMSDI_INVPROTOCOL Mismatch in versions of TP Desktop

ACMSDI_MIXEDMODE All calls on a connection must be either

ACMSDI_NOACMS ACMS system not available. ACMSDI_NOCOMPRESS Gateway does not allow compression. ACMSDI_NOMEMORY Insufﬁcient memory to complete

ACMSDI_NORMAL Normal successful completion. ACMSDI_PENDING Successful operation pending

ACMSDI_PWDEXPIRED Password has expired. ACMSDI_PWDEXPIRING Password expiring in the number of

ACMSDI_SIGNINACTV Sign-in active. ACMSDI_SIGNOUTACTV Sign-out active. ACMSDI_SRVDEAD Node name is invalid, or TP Desktop

Connector client and gateway software.

blocking or nonblocking.

requests.

nonblocking completion. The ﬁnal status is in the completion_status parameter.

hours speciﬁed in options array.

Connector gateway is not running on the speciﬁed node, or the network link terminated.

2–28 TP Desktop Connector Portable API Client Services

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], [completion_routine], [call_context])

Parameters

submitter_id

Type: ACMSDI_SUBMITTER_ID Access: read Mechanism: by reference The submitter identiﬁcation returned by the acmsdi_sign_in service.

acmsdi_sign_out

completion_status

Type: int Access: write Mechanism: by reference The ﬁnal 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 ﬁnal status. See Table 2–7 for a list of the return status values.

completion_routine

Type: function address

For nonblocking only, see Section 2.3.

TP Desktop Connector Portable API Client Services 2–29

acmsdi_sign_out

call_context

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

ACMSDI_INSUFPRM Insufﬁcient parameters. ACMSDI_INTERNAL Internal TP Desktop Connector error. ACMSDI_INVSUBID Invalid or obsolete submitter

ACMSDI_MIXEDMODE All calls on a connection must be either

ACMSDI_NOMEMORY Insufﬁcient memory to complete

ACMSDI_NORMAL Normal successful completion. ACMSDI_PENDING Successful operation pending

ACMSDI_SIGNINACTV Request is invalid while sign-in is

active.

identiﬁcation.

blocking or nonblocking.

requests.

nonblocking completion. The ﬁnal status is in the completion_status parameter.

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 speciﬁed node, or the network link terminated.

TP Desktop Connector Portable API Client Services 2–31

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 Compaq TP Desktop Connector 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,

acmsdi_enable Services a DECforms enable request, which enables

acmsdi_read_msg Services a TDMS Read exchange, which displays

acmsdi_receive Services a DECforms receive request, which sends

which disables a form.

a form.

the prompt, if any, sent from the ACMS task, and

acquires the text from the form’s message ﬁeld.

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

acmsdi_send Services a DECforms send request, which sends

acmsdi_transceive Services a DECforms transceive request, which

acmsdi_write_msg Services a TDMS Write exchange, which displays

a form and transfers data between a form and the application program.

data from the application program to the form.

combines the actions of a send and a receive.

the text sent from the form’s message ﬁeld or the ACMS task.

See Compaq TP Desktop Connector 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 applicationdeﬁned 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 deﬁnition for the exchange step speciﬁes CONTINUE ON FAILURE, the EXC cancels the task for an error status returned.

The TP Desktop Connector kit provides include ﬁles 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 ﬁles 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 deﬁnition. To have a single ACMS application support both DECforms terminals and graphical desktop systems, code the task deﬁnition to check for a DECforms error status value.

3–2 Portable API Presentation Procedures

3.1.2 ACMSDI_FORM_RECORD Structure and Macro Call

Deﬁned in the ACMSDI.H ﬁle, the ACMSDI_FORM_RECORD type declares form records and shadow records passed to and from presentation procedures. The code in Example 3–1 deﬁnes the ACMSDI_FORM_RECORD type and a macro ACMSDI_INIT_FORM_RECORD to initialize the form record structure.

Example 3–1 Form Record Deﬁnition and Initialization Macro

typedef struct {

int data_length; /** length of data record **/ void *data_record; /** pointer to data record **/ int shadow_length; /** length of shadow record **/ void *shadow_record; /** pointer to 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 ﬁle contains function prototypes for the presentation procedures and action routines that your code supplies. The ﬁle PPSTUBS.C contains stub modules you can use for linking your application (see Compaq TP Desktop Connector 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 ﬁrst part handles the generic presentation procedure and dispatches to the application-speciﬁc 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

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_FORMS_SESSION_ID Access: read Mechanism: by reference An identiﬁcation that associates the session with the form speciﬁed in the acmsdi_enable request (see Section 3.5).

acmsdi_disable

call_id

Type: ACMSDI_CALL_ID Access: read Mechanism: by reference The call identiﬁcation 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: read Mechanism: by value Application-speciﬁc 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, ﬁle_speciﬁcation, form_speciﬁcation, forms_print_ﬁle, forms_language, call_id, call_context)

Parameters

submitter_id

Type: ACMSDI_SUBMITTER_ID Access: read Mechanism: by reference The value returned by the acmsdi_sign_in service (see Section 2.11).

forms_session

Type: ACMSDI_FORMS_SESSION_ID Access: write Mechanism: by reference An identiﬁcation that associates the session with the submitter identiﬁcation. This is a write parameter that customer-supplied presentation procedures can ﬁll. Presentation procedures (acmsdi_send, acmsdi_receive, acmsdi_transceive, and acmsdi_disable) can use the forms_session parameter to associate the session with the form speciﬁed 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

ﬁle_speciﬁcation

Type: char * Access: read Mechanism: by reference The form ﬁle speciﬁcation from the ACMS task group deﬁnition. Refer to

Compaq TP Desktop Connector for ACMS Client Application Programming Guide for guidelines on specifying the form ﬁle speciﬁcation.

form_speciﬁcation

Type: char * Access: read Mechanism: by reference The form name speciﬁed in the exchange step in the ACMS task deﬁnition. Refer to Compaq TP Desktop Connector for ACMS Client Application Programming Guide for guidelines on specifying the form name.

forms_print_ﬁle

Type: char * Access: read Mechanism: by reference The DECforms speciﬁcation for the user in ACMSUDF.DAT.

forms_language

Type: char * Access: read Mechanism: by reference The DECforms speciﬁcation for the user in ACMSUDF.DAT.

call_id

Type: ACMSDI_CALL_ID Access: read Mechanism: by reference The call identiﬁcation returned by the acmsdi_call_task service.

call_context

Type: void * Access: read Mechanism: by value Application-speciﬁc 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

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 form’s 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: read Mechanism: by reference The value returned by the acmsdi_sign_in service.

acmsdi_read_msg

msg_text

Type: char Access: write Mechanism: by reference A buffer into which the presentation procedure will write the text from the form’s 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: char Access: read Mechanism: by reference 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 ﬁrst position.

Portable API Presentation Procedures 3–9

acmsdi_read_msg

call_id

Type: ACMSDI_CALL_ID Access: read Mechanism: by reference The call identiﬁcation returned by the acmsdi_call_task service which initiated the ACMS task associated with this exchange.

call_context

Type: void * Access: read Mechanism: by value Application-speciﬁc 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, deﬁned 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 deﬁned in TDMS.H.

3–10 Portable API Presentation Procedures

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_identiﬁer, receive_record_count, receive_control_text, receive_control_text_count, send_control_text, send_control_text_count, timeout, call_id, call_context, receive_record)

acmsdi_receive

Parameters

forms_session

Type: ACMSDI_FORMS_SESSION_ID Access: read Mechanism: by reference An identiﬁcation to associate the session with the form speciﬁed in the acmsdi_ enable request (see Section 3.5).

receive_record_identiﬁer

Type: char * Access: read Mechanism: by reference The form record name or record list name speciﬁed in the RECEIVE request in the ACMS task. Refer to Compaq TP Desktop Connector for ACMS Client Application Programming Guide for guidelines on specifying the form name.

receive_record_count

Type: long int Access: read Mechanism: by value The number of receive record items sent from the ACMS task.

Portable API Presentation Procedures 3–11

acmsdi_receive

receive_control_text

Type: char * Access: write Mechanism: by reference A 25-character string that the customer-supplied request can use to return receive control text.

receive_control_text_count

Type: long int Access: write Mechanism: by reference The number of receive control text items that the customer-supplied request returns.

send_control_text

Type: char * Access: read Mechanism: by reference Send control text sent from the ACMS task.

send_control_text_count

Type: long int Access: read Mechanism: by value The number of send control text items sent from the ACMS task.

timeout

Type: short int Access: read Mechanism: by value A timeout value for user input processing sent from the ACMS task.

call_id

Type: ACMSDI_CALL_ID Access: read Mechanism: by reference The call identiﬁcation returned by the acmsdi_call_task service.

call_context

Type: void * Access: read Mechanism: by value Application-speciﬁc 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

receive_record

Type: ACMSDI_FORM_RECORD array Access: write Mechanism: by reference 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.

acmsdi_receive

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: read Mechanism: by reference The value returned by the acmsdi_sign_in service (see Section 2.11).

request_name

Type: char * Access: read Mechanism: by reference The name of the TDMS request speciﬁed in the ACMS task.

workspace_count

Type: long int Access: read Mechanism: by value The number of workspaces sent from the ACMS task.

3–14 Portable API Presentation Procedures

workspaces

Type: ACMSDI_WORKSPACE array Access: read/write Mechanism: by reference 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: read Mechanism: by reference The call identiﬁcation returned by the acmsdi_call_task service.

call_context

Type: void * Access: read Mechanism: by value Application-speciﬁc context for the call. This is the same context that was passed by the application to the acmsdi_call_task() call.

Return Status

acmsdi_request

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_identiﬁer, 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_FORMS_SESSION_ID Access: read Mechanism: by reference An identiﬁcation that associates the session with the form speciﬁed in the acmsdi_enable request (see Section 3.5).

send_record_identiﬁer

Type: char * Access: read Mechanism: by reference The form record name or record list name speciﬁed in the SEND request in the ACMS task. Refer to Compaq TP Desktop Connector for ACMS Client Application Programming Guide for guidelines on specifying the form name.

send_record_count

Type: long int Access: read Mechanism: by value The number of send record items sent from the ACMS task.

3–16 Portable API Presentation Procedures

acmsdi_send

receive_control_text

Type: char * Access: write Mechanism: by reference A 25-character string that the customer-supplied request can use to return receive control text.

receive_control_text_count

Type: long int Access: write Mechanism: by reference The number of receive control text items that the customer-supplied request returns.

send_control_text

Type: char * Access: read Mechanism: by reference Send control text sent from the ACMS task.

send_control_text_count

Type: long int Access: read Mechanism: by value The number of send control text items sent from the ACMS task.

timeout

Type: short int Access: read Mechanism: by value A timeout value for user input processing, sent from the ACMS task.

call_id

Type: ACMSDI_CALL_ID Access: read Mechanism: by reference The call identiﬁcation returned by the acmsdi_call_task service.

call_context

Type: void * Access: read Mechanism: by value Application-speciﬁc 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_FORM_RECORD array Access: read Mechanism: by reference 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

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_identiﬁer, send_record_count, receive_record_identiﬁer, 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)

acmsdi_transceive

Parameters

forms_session

Type: ACMSDI_FORMS_SESSION_ID Access: read Mechanism: by reference An identiﬁcation that associates the session with the form speciﬁed in the acmsdi_enable request (see Section 3.5).

send_record_identiﬁer

Portable API Presentation Procedures 3–19

acmsdi_transceive

send_record_count

Type: long int Access: read Mechanism: by value The number of send record items sent from the ACMS task.

receive_record_identiﬁer

receive_record_count

Type: long int Access: read Mechanism: by value The number of receive record items sent from the ACMS task.

receive_control_text

Type: char * Access: write Mechanism: by reference A 25-character string that the customer-supplied request can use to return receive control text.

receive_control_text_count

Type: long int Access: write Mechanism: by reference The number of receive control text items that the customer-supplied request returns.

send_control_text

Type: char * Access: read Mechanism: by reference Send control text sent from the ACMS task.

3–20 Portable API Presentation Procedures

acmsdi_transceive

send_control_text_count

Type: long int Access: read Mechanism: by value The number of send control text items sent from the ACMS task.

timeout

Type: short int Access: read Mechanism: by value A timeout value for user input processing, sent from the ACMS task.

call_id

Type: ACMSDI_CALL_ID Access: read Mechanism: by reference The call identiﬁcation returned by the acmsdi_call_task service.

call_context

Type: void * Access: read Mechanism: by value Application-speciﬁc context for the call. This is the same context that was passed by the application to the acmsdi_call_task() call.

send_record

receive_record

Type: ACMSDI_FORM_RECORD array Access: write Mechanism: by reference 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

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 form’s Message Field.

Format

acmsdi_write_msg (submitter_id,

msg_text, call_id, call_context)

Parameters

submitter_id

Type: ACMSDI_SUBMITTER_ID Access: read Mechanism: by reference The value returned by the acmsdi_sign_in service.

acmsdi_write_msg

msg_text

Type: char Access: read Mechanism: by reference Text to be displayed in the form’s Message Field. This is a C-style nullterminated 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: read Mechanism: by reference The call identiﬁcation returned by the acmsdi_call_task service which initiated the ACMS task associated with this exchange.

call_context

Return Status

This function returns a ps32, deﬁned 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 deﬁned in TDMS.H.

3–24 Portable API Presentation Procedures

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 Compaq TP Desktop Connector 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 Compaq TP Desktop Connector for ACMS Client Application Programming Guide).

Format

acmsdi_check_version (form_ﬁle,

version)

acmsdi_check_version

Parameters

form_ﬁle

Type: char * Access: read Mechanism: by reference Speciﬁcation of a form ﬁle or a request library from the ACMS task group deﬁnition.

version

Type: char * Access: read Mechanism: by reference 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 ﬂag that causes the acmsdi_enable routine to terminate with a failure status.

3–26 Portable API Presentation Procedures

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_ﬁle,

version)

Parameters

form_ﬁle

Type: char * Access: read Mechanism: by reference Form ﬁle or request library speciﬁcation from the ACMS task group deﬁnition.

acmsdi_get_version

version

Type: char * Access: write Mechanism: by reference Twenty-four bytes in which the routine writes the version number or date associated with the speciﬁed form ﬁle. 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

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 Compaq TP Desktop Connector 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

acmsdi_bind_enable_args Retrieves write-only arguments in an enable

acmsdi_bind_msg Sends or acquires the message text in TDMS Read

the ACMS status message and task argument workspaces.

exchange step request.

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,

acmsdi_bind_request_args Provides the client application with the request

acmsdi_bind_request_wksps Services a TDMS exchange step, which transfers

acmsdi_bind_send_args Provides the client application with the send record

acmsdi_bind_send_recs Services send and transceive exchange steps, which

acmsdi_bind_session_id Sends the forms session identiﬁer to the TP Desktop

acmsdi_bind_transceive_args Provides the client application with the send and

acmsdi_poll Returns the message type of a message from the

which send data from the desktop client to the TP Desktop Connector gateway.

name and identiﬁes the set of workspaces in a TDMS request exchange step.

data between a desktop client and the TP Desktop Connector gateway.

identiﬁer and identiﬁes the records to be received in a send exchange step.

send data from the TP Desktop Connector gateway to the desktop client.

gateway during an enable exchange step.

receive record identiﬁers and identiﬁes the records to be passed in a transceive exchange step.

back end and a pointer to the call context from the client application.

4.1.1 ACMSDI_FORM_RECORD_BIND Structure

Deﬁned in the ACMSDI.H and ACMSDI.BAS ﬁles, the ACMSDI_FORM_RECORD type declares form records and shadow records transferred. The code in Example 4–1 deﬁnes the ACMSDI_FORM_RECORD_ BIND type for the C language.

4–2 Forced Nonblocking Client Services

Example 4–1 Form Record Deﬁnition

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; /** pointer to data record **/

unsigned int shadow_buffer_len; /** length of callers shadow buffer **/ unsigned int shadow_rec_len; /** actual length of shadow record **/ void *shadow_record; /** pointer to shadow record **/

} ACMSDI_FORM_RECORD_BIND;

4.1.2 ACMSDI_WORKSPACE_BIND Structure

Deﬁned in the ACMSDI.H ﬁle, 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 deﬁnes the ACMSDI_WORKSPACE_BIND type structure.

Example 4–2 Workspace Structure Deﬁnition

typedef struct {

unsigned int buffer_len; /** length of caller’s buffer **/ unsigned int wksp_len; /** actual length of the workspace **/ void *data; /** 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: read Mechanism: by reference The submitter_id returned by the acmsdi_sign_in service.

completion_status

Type: int Access: write Mechanism: by reference The ﬁnal status of the TP Desktop Connector client service. When the service completes, the completion_status parameter contains the ﬁnal status. For the list of return status values, see Table 4–2.

call_id

Type: ACMSDI_CALL_ID * Access: read Mechanism: by reference

4–4 Forced Nonblocking Client Services

acmsdi_complete_call

A structure deﬁned in the ACMSDI.H include ﬁle into which the acmsdi_call_ task service writes a newly created call identiﬁcation, 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

Caution

workspaces

Type: ACMSDI_WORKSPACE or ACMSDI_WORKSPACE_OPT array Access: write Mechanism: by reference 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 speciﬁed in the same order as they are declared in the task deﬁnition, and must match the number speciﬁed 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

ACMSDI_INSUFPRM Insufﬁcient parameters. ACMSDI_INTERNAL Internal TP Desktop Connector error. ACMSDI_INVCALLID Invalid or obsolete call identiﬁcation. ACMSDI_INVSUBID Invalid or obsolete submitter identiﬁcation. ACMSDI_MIXEDMODE Not a forced nonblocking session. ACMSDI_NORMAL Normal successful completion. ACMSDI_WRONG_STATE Session is in the wrong state for this call.

processing is active.

4–6 Forced Nonblocking Client Services

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,

ﬁle_speciﬁcation, form_speciﬁcation, form_version, forms_print_ﬁle, forms_language, call_id)

Parameters

submitter_id

Type: ACMSDI_SUBMITTER_ID Access: read Mechanism: by reference The value returned by the acmsdi_sign_in service (see Section 2.11).

acmsdi_bind_enable_args

ﬁle_speciﬁcation

Type: char * Access: write Mechanism: by reference The form ﬁle speciﬁcation from the ACMS task group deﬁnition. Refer to

Compaq TP Desktop Connector for ACMS Client Application Programming Guide for guidelines on specifying the form ﬁle speciﬁcation.

form_speciﬁcation

Type: char * Access: write Mechanism: by reference The form name speciﬁed in the exchange step in the ACMS task deﬁnition. Refer to Compaq TP Desktop Connector 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: char * Access: write Mechanism: by reference 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_ﬁle

Type: char * Access: write Mechanism: by reference The DECforms speciﬁcation for the user in ACMSUDF.DAT.

forms_language

Type: char * Access: write Mechanism: by reference The DECforms speciﬁcation for the user in ACMSUDF.DAT.

call_id

Type: ACMSDI_CALL_ID * Access: write Mechanism: by reference A pointer to the call identiﬁcation returned by the acmsdi_call_task service. To identify the original task call, compare this pointer with a reference pointer to the call identiﬁer 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 Insufﬁcient parameters. ACMSDI_INVSUBID Invalid or obsolete submitter identiﬁcation. ACMSDI_MIXEDMODE Not a forced nonblocking session. ACMSDI_NORMAL 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-justiﬁed in the buffer and right-ﬁlled 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: read Mechanism: by reference The value returned by the acmsdi_sign_in service.

direction

Type: short int Access: read Mechanism: by value 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 application’s 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 application’s memory.

length

Type: short int Access: read Mechanism: by value The length of the text being sent or the length of the buffer to receive the text; speciﬁcally one of the following:

• the length of the buffer in the application’s 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 application’s memory which is to receive the

message text for a TDMS Write exchange.

text

Type: char Access: read/write Mechanism: by reference 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: write Mechanism: by reference Pointer to the call identiﬁcation returned by the acmsdi_call_task service. To identify the original task call, compare this pointer with a reference pointer to the call identiﬁer obtained by acmsdi_return_pointer.

Return Status

This function returns an int value representing a valid TP Desktop Connector status code as deﬁned 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 Insufﬁcient parameters. ACMSDI_INVSUBID Invalid or obsolete submitter identiﬁcation. ACMSDI_MIXEDMODE Not a forced nonblocking session call. ACMSDI_NORMAL Normal successful completion. ACMSDI_WRONG_BIND Trying to bind arguments for an exchange that

is not in progress.

4–12 Forced Nonblocking Client Services

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 identiﬁer and identiﬁes 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_identiﬁer, receive_record_count, timeout, call_id)

Parameters

acmsdi_bind_receive_args

submitter_id

Type: ACMSDI_SUBMITTER_ID Access: read Mechanism: by reference The submitter_id returned by the acmsdi_sign_in service.

forms_session

Type: ACMSDI_FORMS_SESSION_ID Access: write Mechanism: by reference An identiﬁcation to associate the session with the form speciﬁed in the acmsdi_ enable request (see Section 4.11).

receive_record_identiﬁer

Type: char * Access: write Mechanism: by reference The form record name or record list name speciﬁed in the RECEIVE request in the ACMS task. Refer to Compaq TP Desktop Connector 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: long int Access: write Mechanism: by reference 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: short int Access: write Mechanism: by reference A timeout value for user input processing sent from the ACMS task. TP Desktop Connector writes the timeout value into this location.

call_id

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

4–14 Forced Nonblocking Client Services

is not in progress.

4.6 acmsdi_bind_receive_recs

The client application calls this service to send the client application’s 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_ﬂag, receive_record)

Parameters

submitter_id

Type: ACMSDI_SUBMITTER_ID Access: read Mechanism: by reference The value returned by the acmsdi_sign_in service (see Section 2.11).

acmsdi_bind_receive_recs

receive_control_text_ﬂag

Type: short integer Access: read Mechanism: by value 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_FORM_RECORD_BIND array Access: read Mechanism: by reference 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 Compaq TP Desktop Connector for ACMS Client Application Programming Guide). If the send_control_text_ﬂag contains a value of 1, the ﬁrst 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

is not in progress.

4–16 Forced Nonblocking Client Services

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 writeonly arguments passed from the TP Desktop Connector client services. This provides the client application with the request name and and identiﬁes 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: read Mechanism: by reference The value returned by the acmsdi_sign_in service (see Section 2.11).

acmsdi_bind_request_args

request_name

Type: char * Access: write Mechanism: by reference The name of the TDMS request speciﬁed in the ACMS task.

workspace_count

Type: long int Access: write Mechanism: by reference 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: write Mechanism: by reference The call identiﬁcation returned by the acmsdi_call_task service. To identify the original task call, compare this pointer with a reference pointer to the call identiﬁer 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

is not in progress.

4–18 Forced Nonblocking Client Services

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 modiﬁcation, use this call again to copy the modiﬁed 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: read Mechanism: by reference The value returned by the acmsdi_sign_in service (see Section 2.11).

acmsdi_bind_request_wksps

direction

Type: short int Access: read Mechanism: by value The value indicates which direction the workspaces are being sent. A value of 1 indicates that the workspaces are being copied into the application’s memory from ACMS. A value of 0 indicates that the workspaces are being copied to ACMS from the application’s memory.

workspaces

Type: ACMSDI_WORKSPACE_BIND array Access: read/write Mechanism: by reference The workspace data sent from the ACMS task. One or more workspace arguments can be sent from and returned to the task (see Compaq TP Desktop Connector 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

is not in progress.

4–20 Forced Nonblocking Client Services

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 identiﬁer and identiﬁes 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_identiﬁer, send_record_count, timeout, call_id)

Parameters

acmsdi_bind_send_args

submitter_id

Type: ACMSDI_SUBMITTER_ID Access: read Mechanism: by reference The submitter_id returned by the acmsdi_sign_in service.

forms_session

Type: ACMSDI_FORMS_SESSION_ID Access: write Mechanism: by reference An identiﬁcation that associates the session with the form speciﬁed in the acmsdi_enable request (see Section 4.11).

send_record_identiﬁer

Type: char * Access: write Mechanism: by reference The form record name or record list name speciﬁed in the SEND request in the ACMS task. Refer to Compaq TP Desktop Connector 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: long int Access: write Mechanism: by reference The number of send record items sent from the ACMS task. TP Desktop Connector writes the send_record_count into this location.

timeout

Type: short int Access: write Mechanism: by reference A timeout value for user input processing, sent from the ACMS task. TP Desktop Connector writes the timeout value into this location.

call_id

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

4–22 Forced Nonblocking Client Services

is not in progress.

Compaq TP DESKTOP CONNECTOR AAPVNFGTE User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual