| Previous | Contents | Index |
acmsdi_bind_send_recs (submitter_id,
send _control_text_flag,
send _record)
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.
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.
acmsdi_bind_session_id (submitter_id,
forms _session)
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.
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.
acmsdi_bind_transceive_args submitter_id,
forms _session,
send _record_identifier,
send _record_count,
receive _record_identifier,
receive _record_count,
timeout,
call _id)
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.
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.
acmsdi_poll (submitter_id,
call-context )
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.
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.
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.
| 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. | |
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.
DBBreak (sessID,
reserved,
reserved )
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.
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.
DBEnd (sessID,
reserved )
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.
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 |