Compaq TP Desktop Connector
for ACMS
Client Application Programming Guide


Previous Contents Index

7.4.7 Transceive Exchange Step Arguments

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 

7.5 Sending and Receiving Forms Records and Workspaces

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.

Note

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.

7.5.1 Receiving Send Forms Records and Control Text

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 

7.5.2 Sending Receive Forms Records and Control Text

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 

7.5.3 Sending and Receiving TDMS Request Workspaces

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 

7.6 Forced Nonblocking Flow of Control

The following steps illustrates a typical flow of control for a transceive exchange step during a forced nonblocking session:

  1. The client application issues an acmsdi_sign_in call, specifying the option ACMSDI_OPT_NONBLK. This option indicates that the session is a forced nonblocking session.
  2. The client application issues an acmsdi_call_task without a completion address. Because it is a forced nonblocking session, TP Desktop Connector ACMSDI expects the acmsdi_poll service calls to check for messages from the back-end application, instead of the acmsdi_dispatch_message service.

    Note

    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.
  3. ACMSDI creates a call task message and sends it to the back-end application.
  4. ACMSDI returns ACMSDI_PENDING status to the client application, indicated that the task call has been successfully sent to the back-end application.
  5. The client application issues an acmsdi_poll service call and receives the status, ACMSDI_EXEC, indicating that the task is still executing on the back-end application.
  6. A message arrives from the back-end application.
  7. The client application issues another acmsdi_poll service call to check for a message from the back-end application.
  8. In response to the acmsdi_poll call, ACMSDI determines that a transceive exchange step request has been received from the back-end application and returns the status, ACMSDI_TRCV_EXCH, to the client application.
  9. The client application issues an acmsdi_bind_transceive_args service, passing transceive request arguments by reference.
  10. In response to the acmsdi_bind_transceive_args call, ACMSDI moves the arguments to the client application's memory locations.
  11. From the send and receive record IDs gathered in step 10, the client application knows which forms records are used. The client application issues a series of acmsdi_return_pointer calls to obtain pointers to the send forms records to be placed in the ACMSDI_FORM_RECORD_BIND arrays.
  12. The client application issues an acmsdi_bind_send_recs service, passing the ACMSDI_FORM_RECORD_BIND array for send forms records constructed in step 11.
  13. ACMSDI copies send forms records to the client application's memory locations, including send control text. The client application can now display send forms record data and acquire data from receive forms records in its presentation procedure.
  14. The client application issues a series of acmsdi_return_pointer calls to obtain pointers to the receive forms records to be placed in its ACMSDI_FORM_RECORD_BIND arrays.
  15. The client application issues an acmsdi_bind_receive_recs call, passing receive forms records to ACMSDI with the ACMSDI_FORM_RECORD_BIND array constructed for receive forms records in step 14.
  16. ACMSDI copies receive forms records from the client application's memory locations, including receive control text.
  17. The client application issues an acmsdi_complete_pp service call to indicate that the presentation procedure has completed, passing the status code to be returned to the back-end application.
  18. ACMSDI creates a transceive exchange step response message from the receive forms records copied from the client application in step 16. The transceive response message is sent to the back-end application. The client application can now resume polling for additional exchange steps or task completion messages.


Previous Next Contents Index