# Compaq TP Desktop Connector
for ACMS
Client Services Reference Manual

Previous | Contents | Index

# 4.3 acmsdi_bind_enable_args

The client application can call this service whenever acmsdi_poll returns ACMSDI_ENABLE_EXCH from the TP Desktop Connector gateway on the OpenVMS system. This service retrieves the write-only arguments passed from the TP Desktop Connector client services. This is an optional call.

## Format

> acmsdi_bind_enable_args (submitter_id,
> file _specification,
> form _specification,
> form _version,
> forms _print_file,
> forms _language,
> call _id)

## Parameters

> ### submitter_id

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

> ### file_specification

> Type: char *
> Access: write
> Mechanism: by reference
> The form file specification from the ACMS task group definition. Refer to Compaq TP Desktop Connector for ACMS Client Application Programming Guide for guidelines on specifying the form file specification.

> ### form_specification

> Type: char *
> Access: write
> Mechanism: by reference
> The form name specified in the exchange step in the ACMS task definition. Refer to Compaq TP Desktop Connector for ACMS Client Application Programming Guide for guidelines on specifying the form name.

> ### 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_file

> Type: char *
> Access: write
> Mechanism: by reference
> The DECforms specification for the user in ACMSUDF.DAT.

> ### forms_language

> Type: char *
> Access: write
> Mechanism: by reference
> The DECforms specification for the user in ACMSUDF.DAT.

> ### 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_enable_args procedure are described in Table 4-3.

> Table 4-3 acmsdi_bind_enable_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.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 gateway for ACMS on the host OpenVMS system. It performs one of the following functions:

- acquires the prompt text, if any, associated with a TDMS Read exchange
- sends the message text associated with a TDMS Read exchange.
- acquires the message text associated with a TDMS Write exchange.

If the prompt or message text is being acquired, the text is truncated when the buffer supplied is not large enough to hold the entire text. If the buffer is larger than the text being acquired, the text is left-justified in the buffer and right-filled with blank characters.

This is an optional call, that is, you are not required to issue this call. However, if you do not issue this call you will not be able to process arguments received from the server or to send arguments back to the server.

## Format

> acmsdi_bind_msg (submitter_id,
> direction,
> length,
> text,
> call _id)

## Parameters

> ### submitter_id

> Type: ACMSDI_SUBMITTER_ID
> Access: 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 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; specifically 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 identification returned by the acmsdi_call_task service. To identify the original task call, compare this pointer with a reference pointer to the call identifier obtained by acmsdi_return_pointer.

## Return Status

> This function returns an int, which may be a 16-bit or 32-bit integer depending on the operating system. The value will be a valid TP Desktop Connector status code as defined in ACMSDI.H and described in Table 4-4

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

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

## Format

> acmsdi_bind_receive_args (submitter_id,
> forms _session,
> receive _record_identifier,
> receive _record_count,
> timeout,
> call _id)

## Parameters

> ### submitter_id

> Type: ACMSDI_SUBMITTER_ID
> Access: 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).

> ### 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. 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

> 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_receive_args procedure are described in Table 4-5

> Table 4-5 acmsdi_bind_receive_args Return Status Values
> Status | Description
> --- | ---
> ACMSDI_INSUFPRM | Insufficient parameters.
> ACMSDI_INVSUBID | Invalid or obsolete submitter identification.
> 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.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_flag,
> 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).

> ### receive_control_text_flag

> 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_flag contains a value of 1, the first ACMSDI_FORM_RECORD_BIND structure in the array must point to the receive control text buffer. No shadow record is associated with receive control text.

## Return Status

> The status values returned by the acmsdi_bind_receive_recs service are described in Table 4-6

> Table 4-6 acmsdi_bind_receive_recs Return Status Values
> Status | Description
> --- | ---
> ACMSDI_INSUFPRM | 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.7 acmsdi_bind_request_args

The client application can call this service whenever acmsdi_poll returns ACMSDI_REQUEST_EXCH (a TDMS exchange step) from the TP Desktop Connector gateway on the OpenVMS system. This service retrieves the write-only arguments passed from the TP Desktop Connector client services. This provides the client application with the request name and and identifies the set of workspaces to be received from and then sent back to ACMS. This is an optional call.

## Format

> acmsdi_bind_request_args (submitter_id,
> request _name,
> workspace _count,
> call _id)

## Parameters

> ### submitter_id

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

> ### request_name

> Type: char *
> Access: write
> Mechanism: by reference
> The name of the TDMS request specified 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.

> ### call_id

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

## Return Status

> The status values returned by the acmsdi_bind_request_args service are described in Table 4-7.

> Table 4-7 acmsdi_bind_request_args Return Status Values
> Status | Description
> --- | ---
> ACMSDI_INSUFPRM | 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.8 acmsdi_bind_request_wksps

The client application calls this service to copy request workspace data between the client application and the ACMS during a TDMS exchange. Use the acmsdi_bind_request_wksps call to copy request workspace data from TP Desktop Connector gateway to the client application memory. After modification, use this call again to copy the modified contents back to the TP Desktop Connector gateway. Use this service after you have retrieved the exchange step arguments that identify the workspaces from the TP Desktop Connector gateway. This is an optional call.

## Format

> acmsdi_enable (submitter_id,
> direction,
> req _wksp_array)

## Parameters

> ### submitter_id

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

> ### 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).

## Return Status

> The status values returned by the acmsdi_bind_request_wksps service are described in Table 4-8

> Table 4-8 acmsdi_bind_request_wksps Return Status Values
> Status | Description
> --- | ---
> ACMSDI_INSUFPRM | 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.9 acmsdi_bind_send_args

The client application can call this service whenever an acmsdi_poll returns ACMSDI_SEND_EXCH from the TP Desktop Connector gateway on the OpenVMS system. This service retrieves the write-only arguments passed from the TP Desktop Connector client services. This provides the client application with the send record identifier and identifies the set of forms records it receives from ACMS. See also Section 4.10 for information on calls for send forms records and send control text. This is an optional call.

## Format

> acmsdi_bind_send_args (submitter_id,
> forms _session,
> send _record_identifier,
> send _record_count,
> timeout,
> call _id)

## Parameters

> ### submitter_id

> Type: ACMSDI_SUBMITTER_ID
> Access: 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 that associates 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.

> ### 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_send_args procedure are described in Table 4-9.

> Table 4-9 acmsdi_bind_send_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.

Previous | Next | Contents | Index