# Compaq TP Desktop Connector
for ACMS
Client Services Reference Manual

Previous | Contents | Index

# 4.10 acmsdi_bind_send_recs

The client application calls this service to retrieve send forms record data from the TP Desktop Connector gateway on the OpenVMS system. Use this service after you have retrieved the exchange step arguments that identify the forms records required from the TP Desktop Connector gateway. This service can also be used to retrieve send control text from the TP Desktop Connector gateway. This is an optional call.

## Format

> acmsdi_bind_send_recs (submitter_id,
> send _control_text_flag,
> send _record)

## Parameters

> ### submitter_id

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

> ### send_control_text_flag

> Type: short integer
> Access: read
> Mechanism: by value
> A value of 1 indicates that send control text is to be copied from the ACMS task. A value of 0 indicates that send control text is not to be copied.

> ### send_record

> Type: ACMSDI_FORM_RECORD_BIND array
> Access: write
> Mechanism: by reference
> An array of ACMSDI_FORM_RECORD_BIND structures pointing to buffers containing application data and shadow records sent from the ACMS task (see Compaq TP Desktop Connector for ACMS Client Application Programming Guide). If the send_control_text_flag contains a value of 1, the first ACMSDI_FORM_RECORD_BIND structure in the array must point to the send control text buffer. There is no shadow record associated with send control text.

## Return Status

> The status values returned by the acmsdi_bind_send_recs service are described in Table 4-10.

> Table 4-10 acmsdi_bind_send_recs Return Status Values
> Status | Description
> --- | ---
> ACMSDI_INSUFPRM | Insufficient parameters.
> ACMSDI_INVSUBID | Invalid or obsolete submitter identification.
> 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.

# 4.11 acmsdi_bind_session_id

You can issue the acmsdi_bind_session_id service to send the forms session ID argument to ACMS during an enable exchange step. This is an optional call.

## Format

> acmsdi_bind_session_id (submitter_id,
> forms _session)

## Parameters

> ### submitter_id

> Type: ACMSDI_SUBMITTER_ID
> Access: 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: read
> Mechanism: by reference
> An identification that associates the session with the submitter identification. The user-written application can use the forms_session parameter to associate the session with the form specified in the enable request. The TP Desktop Connector run-time system passes this parameter to subsequent requests to specify which form to use.

## Return Status

> The status values returned by the acmsdi_bind_session_id procedure are described in Table 4-11.

> Table 4-11 acmsdi_bind_session_id Return Status Values
> Status | Description
> --- | ---
> ACMSDI_INSUFPRM | Insufficient parameters.
> ACMSDI_INVSUBID | Invalid or obsolete submitter identification.
> 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.

# 4.12 acmsdi_bind_transceive_args

The client application can call this service whenever an acmsdi_poll returns ACMSDI_TRCV_EXCH from the TP Desktop Connector gateway on the OpenVMS system. This service retrieves the write-only arguments passed from the TP Desktop Connector client services. This provides the client application with the send and receive record identifiers and identifies the set of forms records to be received from and sent to ACMS. See Section 4.6 for information on calls for receive forms records and receive control text. See Section 4.10 for information on calls for send forms records and send control text. This is an optional call.

## Format

> acmsdi_bind_transceive_args submitter_id,
> forms _session,
> send _record_identifier,
> send _record_count,
> receive _record_identifier,
> receive _record_count,
> timeout,
> call _id

> )

## Parameters

> ### submitter_id

> Type: ACMSDI_SUBMITTER_ID
> Access: 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 identification to associate the session with the form specified in the acmsdi_enable request (see Section 4.11).

> ### send_record_identifier

> Type: char *
> Access: write
> Mechanism: by reference
> The form record name or record list name specified 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: 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.

> ### receive_record_identifier

> Type: char *
> Access: write
> Mechanism: by reference
> The form record name or record list name specified 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: write
> Mechanism: by reference
> The number of receive record items sent from the ACMS task. 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

> Type: ACMSDI_CALL_ID *
> Access: write
> Mechanism: by reference
> A pointer to the call identification returned by the acmsdi_call_task service. To identify the original task call, compare this pointer with a reference pointer to the call identifier obtained by acmsdi_return_pointer.

## Return Status

> The status values returned by the acmsdi_bind_transceive_args service are described in Table 4-12.

> Table 4-12 acmsdi_bind_transceive_args Return Status Values
> Status | Description
> --- | ---
> ACMSDI_INSUFPRM | Insufficient parameters.
> ACMSDI_INVSUBID | Invalid or obsolete submitter identification.
> 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.

# 4.13 acmsdi_poll

TP Desktop Connector client programs call this nonblocking service to check for and process messages sent from a TP Desktop Connector gateway to an active submitter in the desktop application. The application must periodically call this service in a forced nonblocking environment to check for completion of outstanding acmsdi_sign_in, acmsdi_call_task, acmsdi_cancel, and acmsdi_sign_out requests. The acmsdi_poll call also checks for the arrival of an exchange step from the back end. (For more information, see Compaq TP Desktop Connector for ACMS Client Application Programming Guide).

The acmsdi_poll service returns a pointer to the call context acquired from the user application when the just-completed call was issued. Storage for this 32-bit integer must exist in the client application's memory. The client application can compare this pointer with that returned by the acmsdi_return_pointer service to identify the completed call. The call context is identified by matching the values.

## Format

> acmsdi_poll (submitter_id,
> call-context )

## Parameters

> ### submitter_id

> Type: ACMSDI_SUBMITTER_ID
> Access: read
> Mechanism: by reference
> The submitter_id returned by the acmsdi_sign_in service. The submitter identifier is used to identify the submitter for which the call is being issued. The acmsdi_poll service passes the submitter identifier as a read-only argument. TP Desktop Connector responds with either the message type received from the back end for that submitter or a return code indicating that there is no message.

> ### call_context

> Type: void *
> Access: write
> Mechanism: by reference
> This call writes the pointer to the call context into this optional parameter. This context identifies the call message that has arrived from the back end. For example, if an acmsdi_call_task completion message is sent from the back end, this is a pointer to the context supplied on the acmsdi_call_task call.

> This pointer to a structure in the client application's memory is treated as a 32-bit integer. To determine the structure being referenced, the client application compares this value with the values returned by the acmsdi_return_pointer service. Because data can be moved by memory management, acmsdi_return_pointer calls must be issued within the same procedure as the original call.

## Return Status

> The status values returned by the acmsdi_poll service are listed in Table 4-13.

> Table 4-13 acmsdi_poll Return Status Values
> Status | Description
> --- | ---
> ACMSDI_CANCEL_DONE | Task cancel call complete.
> ACMSDI_DONE | Sign-in, sign-out, or task call complete.
> ACMSDI_ENABLE_EXCH | Enable exchange step has arrived.
> ACMSDI_EXCHACTV | Request is invalid while exchange step processing is active.
> ACMSDI_EXEC | No message from the back-end available; call still executing.
> ACMSDI_INSUFPRM | Insufficient or conflicting parameters.
> ACMSDI_INVSUBID | Invalid or obsolete submitter identification.
> ACMSDI_INTERNAL | Internal TP Desktop Connector error.
> ACMSDI_MIXEDMODE | Not a forced nonblocking session call.
> ACMSDI_NOMEMORY | Insufficient memory.
> ACMSDI_READY | No message from the back-end available; no call executing.
> ACMSDI_RECV_EXCH | Receive exchange step has arrived.
> ACMSDI_REQUEST_EXCH | TDMS Request exchange step has arrived.
> ACMSDI_SEND_EXCH | Send exchange step has arrived.
> ACMSDI_SRVDEAD | TP Desktop Connector gateway is not running on the server node, or the network link has been terminated.
> ACMSDI_TDMS_READ_EXCH | TDMS Read exchange has arrived
> ACMSDI_TDMS_WRITE_EXCH | TDMS Write exchange has arrived
> ACMSDI_TRCV_EXCH | Transceive exchange step has arrived.

# Chapter 5
Client Services for Macintosh Software

This chapter describes the client services that the Compaq TP Desktop Connector for ACMS software provides on the Macintosh system.

# 5.1 Summary of Client Services for Macintosh Software

Table 5-1 summarizes the Compaq TP Desktop Connector client services.

Table 5-1 Summary of Client Services for Macintosh Software
| Service | Description
--- | --- | ---
Initialization |
| InitDBPack | Initializes the Data Access Manager (DAM) software.
Control |
| DBBreak | Cancels an active ACMS task.
| DBEnd | Requests the TP Desktop Connector gateway to sign a desktop client program session out of the ACMS system.
| DBGetConnInfo | Returns information about a given session, including the node with which the session is communicating and the current state of the connection.
| DBGetErr | Returns additional desktop client program information when an unexpected status is returned by another TP Desktop Connector client service.
| DBGetSessionNum | Returns the session number for a given session.
| DBInit | Sends an authentication request to a selected TP Desktop Connector gateway. Loads the TP Desktop Connector DDEV and creates a DAM session.
Sending Messages |
| DBSend | Prepares a message of any data type for transmission to the TP Desktop Connector gateway. Used only with modifiable workspaces and header data.
| DBSendItem | Prepares a message of any data type for transmission to the TP Desktop Connector gateway. Used with modifiable and unidirectional workspaces and header data.
| DBExec | Sends the message prepared using either DBSend or DBSendItem.
Receiving Messages |
| DBGetItem | Retrieves data returned from the gateway.
| DBState | Returns status about messages pending from the TP Desktop Connector gateway.

## 5.1.1 Return Status Values

Each service returns a status value defined as Short Int. Only the status codes defined in the related reference sections are valid in the TP Desktop Connector client services. The definitions for the return status values are in the include file ACMSDI_MAC.H.

## 5.1.2 Session Identification Parameter

The DAM interface services parameter sessID corresponds functionally to the ACMS submitter identification used on other platforms.

# 5.2 DBBreak

This service cancels an active task with a remote ACMS system. Do not use the DBBreak service while processing an exchange step request.

To return the results of the DBBreak, issue a DBGetErr before issuing a DBState. Once you issue a DBState, any subsequent DBGetErr returns the results of the task call.

## Format

> DBBreak (sessID,
> reserved,
> reserved )

## Parameters

> ### sessID

> Type: Long Int
> Access: read
> Mechanism: by value
> The ID of the session whose task is to be canceled, as returned by the DBInit service.

> ### reserved

> Type: Boolean
> Access: read
> Mechanism: by value
> Specify FALSE.

> ### reserved

> Type: Long Int
> Access: read
> Mechanism: by reference
> Specify as NULL.

## Return Status

> The status values returned by the DBBreak service are listed in Table 5-2.

> Table 5-2 DBBreak Return Status Values
> Status | Value | Description
> --- | --- | ---
> noErr | 0 | No error
> rcDBError | --802 | The operation has failed
> rcDBBadSessID | --806 | Bad session identification
> rcDBAsyncNotSupp | --809 | DDEV does not support asynchronous calls
> rcDBPackNotInited | --813 | InitDBPack not called

> Note See Appendix A for information on return status values specific to TP Desktop Connector

# 5.3 DBEnd

This service ends a DAM session and terminates its connection, if any, with an ACMS system. A desktop client program must call DBEnd to terminate a session.

## Format

> DBEnd (sessID,
> reserved )

## Parameters

> ### sessID

> Type: Long Int
> Access: read
> Mechanism: by value
> Identification of the session to be terminated, as returned by the DBInit service.

> ### reserved

> Type: Long Int
> Access: read
> Mechanism: by reference
> Specify as NULL.

## Return Status

> The status values returned by the DBEnd service are listed in Table 5-3.

> Table 5-3 DBEnd Return Status Values
> Status | Value | Description
> --- | --- | ---
> noErr | 0 | No error
> rcDBError | --802 | The operation has failed
> rcDBExec | --805 | ACMS task still executing on back end
> rcDBBadSessID | --806 | Bad session identification
> rcDBAsyncNotSupp | --809 | DDEV does not support asynchronous calls
> rcDBPackNotInited | --813 | InitDBPack not called

Previous | Next | Contents | Index