| Previous | Contents | Index |
When acmsdi_poll returns ACMSDI_TRCV_EXCH, the client application can issue an acmsdi_bind_transceive_args service call to retrieve the write-only arguments. You must pass memory by reference for all arguments in the client application. The first argument, submitter ID, is a read-only argument and must represent the same submitter for which acmsdi_poll returned ACMSDI_TRCV_EXCH.
The C-language prototype for acmsdi_bind_transceive_args follows:
int acmsdi_bind_transceive_args (ACMSDI_SUBMITTER_ID *subm_id, /*read-required*/
ACMSDI_FORMS_SESSION_ID *fs_id, /*write-optional*/
char *send_record_id, /*write-optional*/
long *send_record_count, /*write-optional*/
char *receive_record_id, /*write-optional*/
long *receive_record_count, /*write-optional*/
short *timeout, /*write-optional*/
ACMSDI_CALL_ID **call_id); /*write-optional*/
|
After the acmsdi_bind_transceive_args call has successfully executed, the write-only arguments contain the values passed from TP Desktop Connector client services. The client application has the send record identifier and knows which set of forms records it needs to send back to ACMS. Use the acmsdi_bind_send_recs service to receive forms records, including send control text, from TP Desktop Connector. Use acmsdi_bind_receive_recs to send receive forms records, including receive control text, to TP Desktop Connector. You can issue both of these calls before issuing and acmsdi_complete_pp service call.
Example 7-7, written in Visual Basic, illustrates:
| Example 7-7 ACMSDI_TRCV_EXCH Sample |
|---|
Dim call_id As acmsdi_call_id
Dim subm_id As acmsdi_sub_id
Dim forms_sess_id As acmsdi_forms_session_id
Dim send_rec_id As String * 256
Dim send_rec_count As long
Dim recv_rec_id As String * 256
Dim recv_rec_count As Long
Dim timeout As Integer
Dim call_id_retr As Long
Dim status As Integer
status = acmsdi_poll(subm_id, ByVal 0&)
If status = ACMSDI_TRCV_EXCH Then
status = acmsdi_bind_transceive_args(subm_id,
forms_sess_id,
send_rec_id,
send_rec_count,
recv_rec_id,
recv_rec_count,
timeout,
call_id_retr)
If status = ACMSDI_NORMAL Then ' if all OK and ...
If forms_sess_id.session_id = "FORMS_SESS000251" Then ' ...my session
>>> Process Transceive Exchange arguments <<<
End If
Else
>>> Error processing <<<
End If
End If
|
TP Desktop Connector provides three forced nonblocking services to send and receive forms records (for DECforms type exchanges) and workspaces (for TDMS type exchanges) to and from TP Desktop Connector. These services are:
You invoke these services after you retrieve exchange step arguments with one of the services discussed in Section 7.4, because the client application knows what forms record or workspace array is required to be sent and received.
In addition to forms records, you can receive send control text and receive control text from and sent to TP Desktop Connector using these services. TP Desktop Connector does not require that you issue these service calls. However, if you do not issue them, the client application is not able to examine forms records or workspaces sent from TP Desktop Connector and forms records and workspaces sent to TP Desktop Connector will contain default values.
TP Desktop Connector does require that you issue acmsdi_poll to read the messages from the back end, and that you issue acmsdi_complete_pp to signal completion of exchange step processing and to write reply messages to the back end.
In the following sections, send forms records and send control text are received from TP Desktop Connector. Conversely, receive forms records and receive control text are sent to TP Desktop Connector. The adjectives send and receive when applied to forms records and control text are from the back-end perspective. |
Send forms records are forms records that are sent from ACMS to the client application during a send or transceive exchange. Use acmsdi_bind_send_recs to cause send forms record data to be moved to the client application's buffer from TP Desktop Connector. You can also use the acmsdi_bind_send_recs service to cause send control text to be copied to the application's buffers from TP Desktop Connector.
The send record identifier, which you can retrieve with the acmsdi_bind_send_args and acmsdi_bind_transceive_args, implicitly defines the number and types of the forms records. The acmsdi_bind_send_recs service passes an array of ACMSDI_FORM_RECORD_BIND structures as one of its arguments. Each ACMSDI_FORM_RECORD_BIND structure contains two pointers; one to the data record and one to the shadow record. You must declare buffers for these forms records in the client application. If a shadow record is not in use, its pointer can be NULL.
ACMSDI_FORM_RECORD_BIND structures also contain the lengths of the buffers in the client application and a field, initially set to zero, in which ACMS Desktop returns the actual length of the forms records. If the forms record length is greater than the buffer length, forms records are truncated in the buffer. If the forms record length is less than the buffer length, the buffer is not completely filled by forms record data.
You can use the acmsdi_bind_send_recs service to request that send control text be copied to the application from TP Desktop Connector. If the second argument has a value of 1, send control text is to be copied. A value of 0 specifies that send control text is not to be copied. If you specify the send control text, you must specify the corresponding ACMSDI_FORM_RECORD_BIND structure as the first one in the array. When the call terminates, the rec_len field of the ACMSDI_FORM_RECORD_BIND structure contains the send control text count as opposed to the send control text length.
The first argument, the submitter ID, is a read-only argument and must represent the same submitter for which the acmsdi_poll returned ACMSDI_SEND_EXCH or ACMSDI_TRCV_EXCH.
The C-language prototype for acmsdi_bind_send_recs follows:
int acmsdi_bind_send_recs (ACMSDI_SUBMITTER_ID *subm_id, /*read-required*/
int bind_send_ctrl_text, /*read-required*/
ACMSDI_FORM_RECORD_BIND *send_rec_array); /*write-required*/
|
You must declare and initialize the array of ACMSDI_FORM_RECORD_BIND structures before issuing the acmsdi_bind_send_recs call. You can obtain pointers to the forms record buffers by using the acmsdi_return_pointer service. Initialize forms records pointers immediately prior to each issuance of the acmsdi_bind_send_recs service, to assure that they are pointing to the current locations of the forms record buffers.
Example 7-8 illustrates:
| Example 7-8 Sending Forms Records |
|---|
'
' employee forms record type definition
'
Type employee_rec
badge_nbr As Long
name As String * 35
ss_nbr As String * 11
End Type
'
' employee shadow type definition (one byte for each employee record field)
'
Type employee_shadow
badge_nbr As String * 1
name As String * 1
ss_nbr As String * 1
End Type
'
' control forms record type definition
'
Type ctrl_rec
ctrl_count As Integer
total_emps As Integer
End Type
'
' control text type definition
'
Type ctrl_text
ctrl_string(5) As String * 5
End Type
'
' forms record and send control text declarations
'
Dim empl As employee_rec
Dim empl_shdw As employee_shadow
Dim ctrl As ctrl_rec
Dim send_ctrl_text As ctrl_text
'
' ACMSDI_FORM_RECORD_BIND array for send forms records
'
Dim send_recs(3) As ACMSDI_FORM_RECORD_BIND
'
' other declarations
'
Dim subm_id As acmsdi_sub_id
Static status As Long
Const NULL = 0
Dim ctrl_text_flag As Integer
Dim send_ctrl_text_count As Integer
'
' initialize the send forms records array using acmdi_return_pointer to get
' forms record buffer pointers (looking like 32-bit integers)
'
send_recs(0).buffer_len = Len(send_ctrl_text)
send_recs(0).record_len = 0
send_recs(0).data_record = acmsdi_return_pointer(send_ctrl_text)
send_recs(0).shadow_buffer_len = 0
send_recs(0).shadow_rec_len = 0
send_recs(0).shadow_record = NULL
send_recs(1).buffer_len = Len(empl)
send_recs(1).rec_len = 0
send_recs(1).data_record = acmsdi_return_pointer(empl)
send_recs(1).shadow_buffer_len = Len(empl_shdw)
send_recs(1).shadow_rec_len = 0
send_recs(1).shadow_record = acmsdi_return_pointer(empl_shdw)
send_recs(2).buffer_len = Len(ctrl)
send_recs(2).rec_len = 0
send_recs(2).data_record = acmsdi_return_pointer(ctrl)
send_recs(2).shadow_buffer_len = 0
send_recs(2).shadow_rec_len = 0
send_recs(2).shadow_record = NULL
'
' set control text flag to indicate that we want to send control text retrieved
'
ctrl_text_flag = 1
'
' call to get send forms records
'
status = acmsdi_bind_send_recs(subm_id, ctrl_text_flag, send_recs(0))
send_ctrl_text_count = send_recs(0).rec_len
If send_recs(1).buffer_len < send_recs(1).rec_len Then
>>> employee record truncated >>>
ElseIf send_recs(1).buffer_len > send_recs(1).rec_len Then
>>> employee record buffer not completely filled <<<
Else
>>> employee record exactly fits buffer <<<
End If
|
Receive forms records are forms records that are sent from the client application to ACMS during a receive or transceive exchange. Use acmsdi_bind_receive_recs to send the client application's receive forms record buffer contents to TP Desktop Connector. You can also use acmsdi_bind_receive_recs service to cause receive control text to be copied to TP Desktop Connector from the application's buffers.
The receive record identifier argument, retrieved by either acmsdi_bind_receive_args or acmsdi_bind_transceive_args, implicitly defines the number and types of the forms records. The acmsdi_bind_receive_recs service passes an array of ACMSDI_FORM_RECORD_BIND structures as one of its arguments. Each ACMSDI_FORM_RECORD_BIND structure contains two pointers; one to the data record and one to the shadow record. You must declare buffers for these forms records in the client application. If a shadow record is not in use, its pointer can be NULL.
ACMSDI_FORM_RECORD_BIND structures also contain the lengths of the buffers in the client application and a field, initially set to zero, in which TP Desktop Connector returns the actual length of the forms records. If the forms record length is greater than the buffer length, the buffer is not large enough to provide data for the entire forms record. If the forms record length is less than the buffer length, not all of the data in the buffer is transmitted to the back end.
You can use the acmsdi_bind_receive_args service to request that receive control text be copied to TP Desktop Connector. If the second argument has a value of 1, receive control text is copied. A value of 0 specifies that receive control text is not copied. If you specify the receive control text, you must specify its corresponding ACMSDI_FORM_RECORD_BIND structure as the first one in the array. Initialize the rec_len field to contain the receive control text count.
The first argument, the submitter ID, is a read-only argument and must represent the same submitter for which acmsdi_poll returned ACMSDI_RECV_EXCH or ACMSDI_TRCV_EXCH.
The C-language prototype for acmsdi_bind_receive_recs follows:
int acmsdi_bind_receive_recs (ACMSDI_SUBMITTER_ID *subm_id, /*read-required */
int bind_receive_ctrl_text, /*read-required*/
ACMSDI_FORM_RECORD_BIND *recv_rec_array); /*read-required*/
|
You must declare and initialize the array of ACMSDI_FORM_RECORD_BIND structures before issuing the acmsdi_bind_receive_recs call. You can obtain pointers to the forms record buffers using the acmsdi_return_pointer service. Initialize forms record pointers immediately before each issuance of acmsdi_bind_receive_recs service to assure that they are pointing to the current locations of the forms record buffers.
Example 7-9 illustrates:
| Example 7-9 Receiving Forms |
|---|
'
' employee forms record type definition
'
Type employee_rec
badge_nbr As Long
name As String * 35
ss_nbr As String * 11
End Type
'
' employee shadow type definition (one byte for each employee record field)
'
Type employee_shadow
badge_nbr As String * 1
name As String * 1
ss_nbr As String * 1
End Type
'
' control forms record type definition
'
Type ctrl_rec
ctrl_count As Integer
total_emps As Integer
End Type
'
' control text type definition
'
Type ctrl_text
ctrl_string(5) As String * 5
End Type
'
' forms record declarations
'
Dim empl As employee_rec
Dim empl_shdw As employee_shadow
Dim ctrl As ctrl_rec
Dim send_ctrl_text As ctrl_text
'
' ACMSDI_FORM_RECORD_BIND array for receive forms records
'
Dim recv_recs(3) As ACMSDI_FORM_RECORD_BIND
'
' other declarations
'
Dim subm_id As acmsdi_sub_id
Static status As Long
Const NULL = 0
Dim ctrl_text_flag As Integer
Dim send_ctrl_text_count As Integer
'
' initialize receive control text
'
receive_ctrl_text_count = 2
receive_ctrl_text.ctrl_string(0) = "AB001"
receive_ctrl_text.ctrl_string(1) = "CC599"
'
' initialize the receive forms records array using acmdi_return_pointer to get
' forms record buffer pointers (looks like 32-bit integers)
'
recv_recs(0).buffer_len = Len(receive_ctrl_text)
recv_recs(0).record_len = receive_ctrl_text_count
recv_recs(0).data_record = acmsdi_return_pointer(receive_ctrl_text)
recv_recs(0).shadow_buffer_len = 0
recv_recs(0).shadow_rec_len = 0
recv_recs(0).shadow_record = NULL
recv_recs(1).buffer_len = Len(empl)
recv_recs(1).rec_len = 0
recv_recs(1).data_record = acmsdi_return_pointer(empl)
recv_recs(1).shadow_buffer_len = Len(empl_shdw)
recv_recs(1).shadow_rec_len = 0
recv_recs(1).shadow_record = acmsdi_return_pointer(empl_shdw)
recv_recs(2).buffer_len = Len(ctrl)
recv_recs(2).rec_len = 0
recv_recs(2).data_record = acmsdi_return_pointer(ctrl)
recv_recs(2).shadow_buffer_len = 0
recv_recs(2).shadow_rec_len = 0
recv_recs(2).shadow_record = NULL
'
' set control text flag to indicate that we want to receive control text sent
'
ctrl_text_flag = 1
'
' call to send receive forms records
'
status = acmsdi_bind_receive_recs(subm_id, ctrl_text_flag, recv_recs(0))
If recv_recs(1).buffer_len < recv_recs(1).rec_len Then
>>> client application buffer is too small >>>
ElseIf recv_recs(1).buffer_len > recv_recs(1).rec_len Then
>>> client application buffer is too large <<<
Else
>>> client application buffer is exactly the right size <<<
End If
|
Request workspaces are workspaces that are sent from ACMS to the client application and sent back to ACMS during a TDMS Request exchange. Use acmsdi_bind_request_wksps to cause request workspace data to be copied to the client application's buffers from TP Desktop Connector. After the workspaces have been modified, use acmsdi_bind_request_wksps service a second time to send back the modified contents to TP Desktop Connector.
The request name argument, retrieved by the acmsdi_bind_request_args service, implicitly defines the number and types of the workspaces. The acmsdi_bind_request_wksps service passes an array of ACMSDI_WORKSPACE_BIND structures as one of its arguments. Each ACMSDI_WORKSPACE_BIND structure contains a pointer to the workspace buffer. The buffers must be declared in the client application.
ACMSDI_WORKSPACE_BIND structures also contain the lengths of the buffers in the client application and a field, initially set to zero, in which TP Desktop Connector returns the actual length of the workspaces. If the workspace length is less than the buffer length, the buffer is not filled completely by workspace data.
The second argument is an integer indicating the direction in which the workspaces are sent. A value of 1 indicates that the workspaces are copied into the application's buffers from TP Desktop Connector. A value of 0 indicates that workspaces are copied to TP Desktop Connector from the application's buffers.
The first argument, the submitter ID, is a read-only argument and must represent the same submitter for which acmsdi_poll returned ACMSDI_REQUEST_EXCH.
The C-language prototype for acmsdi_bind_request_wksps follows:
int acmsdi_bind_request_wksps (ACMSDI_SUBMITTER_ID *subm_id, /*read-required*/
int direction, /*read=required*/
ACMSDI_WORKSPACE_BIND *req_wksp_array); /*read-write-required*/
|
You must declare and initialize the array of ACMSDI_WORKSPACE_BIND structures issuing the acmsdi_bind_request_wksps call. Obtain pointers to the workspace buffers using the acmsdi_return_pointer service. You must initialize the workspace pointers before each issuance of the acmsdi_bind_request_wksps service to assure that they are pointing to the current locations of the workspace buffers.
Example 7-10 illustrates:
| Example 7-10 TDMS Sample |
|---|
'
' employee workspace type definition
'
Type employee_wksp
badge_nbr As Long
name As String *35
ss_nbr As String * 11
End Type
'
' control workspace definition
'
Type ctrl_wksp
ctrl_count As Integer
total_emps As Integer
End Type
'
' workspace definitions
'
Dim empl As employee_wksp
Dim ctrl As ctrl_wksp
'
' ACMSDI_WORKSPACE_BIND array for TDMS request workspaces
'
' other declarations
'
Dim request_wksps(2) As ACMSDI_WORKSPACE_BIND
Dim status As Long
Const TO_ACMS = 0
Const FROM_ACMS = 1
'
' initialize the TDMS request workspaces array using acmsdi_return_pointer to
' get workspace buffer pointers (looks like 32-bit integers)
'
request_wksps(0).buffer_len = Len(empl)
request_wksps(0).wksp_len = 0
request_wksps(0).data = acmsdi_return_pointer(empl)
request_wksps(1).buffer_len = Len(ctrl)
request_wksps(1).wksp_len = 0
request_wksps(1).data = acmsdi_return_pointer(ctrl)
'
' call to get TDMS request workspaces
'
status = acmsdi_bind_request_wksps(subm_id, FROM_ACMS, request_wksps(0))
If request_wksps(0).buffer_len < request_wksps(0).wksp_len Then
>>> employee record truncated <<<
ElseIf request_wksps(0).buffer_len > request_wksps(0).wksp_len Then
>>> employee record buffer not completely filled <<<
Else
>>> employee record exactly fits buffer <<<
>>> modify workspaces as required <<<
'
' Having modified the workspaces, now send them back to ACMS
request_wksps(0).data = acmsdi_return_pointer(empl) 'update empl pointer
request_wksps(0).data = acmsdi_return_pointer(ctrl) 'update ctrl pointer
status = acmsdi_bind_request_wksps(subm_id, TO_ACMS, request_wksps(0))
End If
|
The following steps illustrates a typical flow of control for a transceive exchange step during a forced nonblocking session:
Issuing an acmsdi_dispatch_message call during a forced nonblocking session causes an error condition, because TP Desktop has no completion address at which to dispatch upon task completion. |
| Previous | Next | Contents | Index |