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