Presentation tools, like Visual Basic, which do not support pointer types, need a mechanism that enables them to cancel a task without specifying a completion routine address. For these tools, TP Desktop Connector provides the polling service, acmsdi_poll, to detect the completion of a task cancellation.

When a client application detects the completion of a task cancellation, the completion status argument acquired with the acmsdi_complete_call service contains the final status of the task cancellation. ACMSDI reports the status of a task cancellation call before the final status of the task call.

7.3.3 Polling for Messages

The acmsdi_poll service is required in a forced nonblocking session, in place of the acmsdi_dispatch_message service. Unlike acmsdi_dispatch_message, which passes no arguments, the acmsdi_poll service passes the submitter identifier created at sign-in, and, optionally, a location where a pointer to the context of the task or cancel call can be returned.

You must issue the acmsdi_poll service for a specific submitter, because acmsdi_poll does not dispatch any messages, but returns the message type of one message received from the back end. In contrast, the acmsdi_dispatch_message service dispatches any number of messages (calls any number of completion routines or presentation procedures) with a single call from the user. Thus, your application must issue acmsdi_poll calls for all submitters it controls.

You can use the pointer to the call context to determine to which call the returned status refers. You must declare, and pass by reference, the memory for the call context in the client application. Because it is unlikely that the client application supports pointer types, the returned pointer is seen as a 32-bit integer. Using the acmsdi_return_pointer service, you can obtain a pointer to the call context as a 32-bit integer. The client application can then compare the two pointers to identify the call. The pointer is an optional argument, therefore, you can pass a zero value indicating that no call context is returned.

7.3.4 Obtaining Completion Arguments

When acmsdi_poll detects the completion of an acmsdi_sign_in, acmsdi_sign_out, acmsdi_call_task, or acmsdi_cancel call in the forced nonblocking environment, you obtain the arguments form the backend using the acmsdi_complete_call service. The final completion status is the only argument to obtain for acmsdi_sign_in, acmsdi_sign_out, and acmsdi_cancel. For acmsdi_call_task, in addition to the final completion status, you also obtain the ACMS status message and task argument workspaces.

The third argument in the acmsdi_complete_call service is an ACMSDI_CALL_ID structure, representing the call ID of the original task call. This argument is required for calls issued to obtain acmsdi_call_task completion argument, but must be NULL for all other call types.

Obtain task argument workspaces by passing an array of ACMSDI_WORKSPACE or ACMSDI_WORKSPACE_OPT structures. You must pass the same array that you passed on the original acmsdi_call_task service call. However, because memory management routines may have relocated the buffers, you must renew the workspace pointers in the ACMSDI_WORKSPACE or ACMSDI_WORKSPACE_OPT structures using the acmsdi_return_pointer service prior to issuing acmsdi_complete_call.

The acmsdi_complete_call is required. Until you issue the acmsdi_complete_call service call, a task call is not considered complete.

The C-language prototype for acmsdi_complete_call is as follows:

int acmsdi_complete_call (ACMSDI_SUBMITTER_ID *subm_id, /*read - required*/ int * completion status, /*write - required*/ ACMSDI_CALL_ID *call_id, /*read - optional*/ char *status_message, /*write - optional*/ void *workspace); /*write - optional*/

7.4 Forced Nonblocking Exchange Step Handling

When acmsdi_poll returns a value indicating that an exchange step request has arrived from the back end, you can issue one of six services to retrieve the write-only arguments:

• acmsdi_bind_enable_args
• acmsdi_bind_msg
• acmsdi_bind_receive_args
• acmsdi_bind_request_args
• acmsdi_bind_send_args
• acmsdi_bind_transceive_args

For enable exchange steps, you can issue the service, acmsdi_bind_session_id, to send the Forms Session ID to ACMS.

TP Desktop Connector does not require that you issue these service calls. However, if you do not issue them, the client application cannot examine the write-only arguments, and value of blanks are sent to ACMS for Forms Session ID. TP Desktop Connector does require that you issue the acmsdi_poll service to read the messages from the back end, and that you issue the acmsdi_complete_pp service to signal completion of exchange step processing.

When acmsdi_poll returns ACMSDI_ENABLE_EXCH, the client application can issue an acmsdi_bind_enable_args service call to retrieve the write-only arguments. You can issue an acmsdi_bind_session_id to send the forms session ID argument to ACMS. For both calls, the first argument, the submitter ID, is a read-only argument and must represent the same submitter for which acmsdi_poll returned ACMSDI_ENABLE_EXCH.

The argument for acmsdi_bind_enable_args are the same as the arguments for the acmsdi_enable presentation procedure with three exceptions:

• One additional argument, the form's version, is included on the acmsdi_bind_enable_args call. The version is included so that version checking can be performed by the client application as part of the form's enable processing.

  Note The acmsdi_check_version callback is not supported for forced nonblocking sessions.

• The call context is not included because it is returned by the acmsdi_poll service call.
• The forms session ID argument is not included because it is a read-only argument that is sent to ACMS using the acmsdi_bind_session_id service call.

You must declare memory for all arguments in the client application and pass them by reference.

The C-language prototype for acmsdi_bind_enable_args follows:

int acmsdi_bind_enable_args (ACMSDI_SUBMITTER_ID *sub_id, /*read-required*/ char *file_specification, /*write-optional*/ char *form_specification, /*write-optional*/ char *form_version, /*write-optional*/ char *forms_print_file, /*write-optional*/ char *forms_language, /*write-optional*/ ACMSDI_CALL_ID **call_id);

After the acmsdi_bind_enable_args call has successfully executed, the write-only arguments contain the value passed from the TP Desktop Connector client services.

The C-language prototype for acmsdi_bind_session_id follows:

int acmsdi_bind_session_id (ACMSDI_SUBMITTER_ID *sub_id, /*read-required*/ ACMSDI_FORMS_SESSION_ID *session_id);

Example 7-1, written in Visual Basic, illustrates:

• Issuance of acmsdi_poll
• Receiving return code ACMSDI_ENABLE_EXCH
• Issuance of acmsdi_bind_enable_args
• Issuance of acmsdi_bind_session_id to send forms session identifier to ACMS

Example 7-1 Visual Basic Sample

Dim call_id As acmsdi_call_id Dim subm_id As acmsdi_sub_id Dim call_id_retr As Long Dim fs_id As acmsdi_forms_session_id Dim filespec As String * 256 Dim formspec As String * 256 Dim formversion As String * 256 Dim formprint As String * 256 Dim formlang As String * 256 Static status As Integer status = acmsdi_poll(subm_id, ByVal 0&) If status = ACMSDI_ENABLE_EXCH Then status = acmsdi_bind_enable_args(subm_id, filespec, formspec, formversion, formprint, formlang, call_id_retr) If status = ACMSDI_NORMAL Then >>> Process Enable arguments <<< fs_id.session_id = "FORMS_SESS000251" 'set forms session id status = acmsdi_bind_session_id(subm_id, fs_id) 'send it to ACMS If status <> ACMSDI_NORMAL Then >>> Error processing <<< End If status = acmsdi_complete_pp(call_id, FORMS_NORMAL) 'end exchange Else >>> Error processing >>> End If End If

7.4.2 TDMS Read Exchange Step Arguments

When acmsdi_poll returns ACMSDI_TDMS_READ_EXCH (a TDMS read exchange step), the client application can issue an acmsdi_bind_msg to retrieve the prompt text and a second acmsdi_bind_msg to send the message text from the forms message field. You must declare memory for both arguments in the client application and pass them by reference.

The C-language prototype for acmsdi_bind_msg follows:

int acmsdi_bind_msg (ACMSDI_SUBMITTER_ID *subm_id, /*read-required*/ short direction, /*read-required*/ short length, /*read-required*/ char *text, /*read or write-required*/ ACMSDI_CALL_ID **call_id); /*write-optional*/

The direction argument is a code indicating one of the following:

• 1 --- indicates that the prompt text is being acquired from ACMS.
• 0 --- indicates that the message text is being sent to ACMS.

After acquiring the prompt text by issuing an acmsdi_bind_msg with direction equal to 1, the prompt may be displayed on the form. The client application then waits for the user to enter message text in the form's message field. After the user indicates that the message text is completely entered, the client application issues a second acmsdi_bind_msg with direction equal to 0 to send the message text to the server.

The first argument, the submitter ID, is a read-only argument and must represent the same submitter for which acmsdi_poll returned ACMSDI_TDMS_READ_EXCH.

Example 7-2 illustrates the following:

• Issuance of acmsdi_bind_msg
• Receiving of return code ACMSDI_TDMS_READ_EXCH
• Issuance of acmsdi_bind_msg to retrieve the prompt text
• Issuance of acmsdi_bind_msg to send the message text

Example 7-2 ACMSDI_TDMS_READ_EXCH Sample

Dim subm_id As acmsdi_sub_id Dim call_id As acmsdi_call_id Dim direction As Integer Dim msg_len As Integer Dim msg_text As String * 80 Dim prompt_len As Integer Dim prompt_text As String * 40 Dim status As Integer status = acmsdi_poll(subm_id, ByVal o&) If status = ACMSDI_TDMS_READ_EXCH Then direction = 1 prompt_len = 40 status = acmsdi_bind_msg(subm_id, direction, prompt_len, prompt_text, ByVal 0&) If status = ACMSDI_NORMAL Then ' ' display prompt on the form and wait for user ' to enter message text in the form's message field ' direction = 0 msg_len = 80 status = acmsdi_bind_msg(subm_id, direction, msg_len, msg_text, ByVal 0&) acmsdi_complete_pp(call_id, TSS_NORMAL) Else >>> Error processing <<< End If End If

7.4.3 TDMS Write Exchange Step Arguments

When acmsdi_poll returns ACMSDI_TDMS_WRITE_EXCH (a TDMS write exchange step) the client application can issue an acmsdi_bind_msg to retrieve the message text. You must declare memory for the message text argument in the client application and pass it by reference.

The C-language prototype for acmsdi_bind_msg follows:

int acmsdi_bind_msg (ACMSDI_SUBMITTER_ID *subm_id, /*read-required*/ short direction, /*read-required*/ short length, /*read-required*/ char *text, /*read or write-required*/ ACMSDI_CALL_ID **call_id); /*write-optional*/

The direction argument is a code indicating that the message text is being retrieved from ACMS. Its value is 1 to indicate retrieval as opposed to sending of the text. After acquiring the message text, the message may be displayed on the form.

The first argument, the submitter ID, is a read-only argument and must represent the same submitter for which acmsdi_poll returned ACMSDI_TDMS_WRITE_EXCH.

Example 7-3 illustrates the following:

• Issuance of acmsdi_poll
• Receiving of return code ACMSDI_TDMS_WRITE_EXCH
• Issuance of acmsdi_bind_msg to retrieve the message text

Example 7-3 ACMSDI_TDMS_WRITE_EXCH Sample

Dim subm_id As acmsdi_sub_id Dim call_id As acmsdi_call_id Dim direction As Integer Dim msg_len As Integer Dim msg_text As String * 80 Dim status As Integer status = acmsdi_poll(subm_id, ByVal 0&) If status = ACMSDI_TDMS_WRITE_EXCH Then direction = 1 msg_len = 80 status = acmsdi_bind_msg(subm_id, direction, msg_len, msg_text, ByVal 0&) If status = ACMSDI_NORMAL Then ' ' display the message on the form's message field ' acmsdi_complete_pp(call_id, TSS_NORMAL) Else >>> Error processing <<< End If End If

7.4.4 Receiving Exchange Arguments

When acmsdi_poll returns ACMSDI_RECV_EXCH, the client application can issue and acmsdi_bind_receive_args service call to retrieve the write-only arguments. The first argument, the submitter ID, is the read-only argument and must represent the same submitter for which acmsdi_poll returned ACMSDI_RECV_EXCH. You can compare the second argument, forms session ID, to the forms session ID sent to ACMS by acmsdi_bind_session_id, to determine the forms session established earlier during an enable exchange.

The arguments for acmsdi_bind_receive_args are the same as the arguments for the acmsdi_receive presentation procedure except that the receive control text and the send control text are not included. These arguments are treated as forms records, and, therefore, are handled by acmsdi_bind_receive_recs and acmsdi_bind_send_recs.

You must declare memory for all arguments in the client application and pass them by reference.

The C-language prototype for acmsdi_bind_receive_args follows:

int acmsdi_bind_receive_args (ACMSDI_SUBMITTER_ID *sub_id, /*read-required*/ ACMSDI_FORMS_SESSION_ID *fs_id, /*write-optional*/ char *receive_record_id, /*write-optional*/ long *receive_record_count, /*write-optional*/ short *timeout, /*write-optional*/ ACMSDI_CALL_ID **call_id);

After the acmsdi_bind_receive_args has successfully executed, the write-only arguments contain the values passed from TP Desktop Connector client services. The client application has the receive record identifier and knows which set of forms records it needs to send back to ACMS. You can send receive forms records, including receive control text, to TP Desktop Connector using the acmsdi_bind_receive_recs service. You can obtain the send control text using the acmsdi_bind_send_recs service.

Example 7-4, written in Visual Basic, illustrates:

• Issuance of acmsdi_poll
• Receiving return code ACMSDI_RECV_EXCH
• Issuance of acmsdi_bind_receive_args

Example 7-4 ACMSDI_RECV_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 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_RECV_EXCH Then status = acmsdi_bind_receive_args(subm_id, forms_sess_id, recv_rec_id, recv_rec_count, timeout, call_id_retr) If status = ACMSDI_NORMAL Then 'if all OK and ... If form_sess_id.session_id = "FORMS_SESS000251" Then ' ...my session >>> Process Receive Exchange arguments for my form >>> acmsdi_complete_pp(call_id, FORMS_NORMAL) End If Else >>> Error processing <<< End If End If

7.4.5 Requesting Exchange Step Arguments

When acmsdi_poll returns ACMSDI_REQUEST_EXCH (a TDMS exchange step) the client application can issue an acmsdi_bind_request_args to retrieve the write-only arguments. You must declare memory for all arguments in the client application and pass them by reference.

The C-language prototype for acmsdi_bind_request_args follows:

int acmsdi_bind_request_args (ACMSDI_SUBMITTER_ID *subm_id, /*read-required*/ char *request_name, /*write-optional*/ long *workspace_count, /*write-optional*/ ACMSDI_CALL_ID **call_id); /*write-optional*/

After the acmsdi_bind_request_args call has successfully executed, the write-only arguments contain the values passed from TP Desktop Connector client services. The client application has the request name and knows which set of workspaces it will be receiving and sending back to ACMS. Use acmsdi_bind_request_wksps to receive workspaces from TP Desktop Connector. You must must modify these workspaces appropriately before issuing a second acmsdi_bind_request_wksps call to send them back to ACMS.

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.

Example 7-5 illustrates the following:

• Issuance of acmsdi_poll
• Receiving of return code ACMSDI_REQUEST_EXCH
• Issuance of acmsdi_bind_request_args

Example 7-5 ACMSDI_REQUEST_EXCH Sample

Dim subm_id As acmsdi_sub_id Dim call_id As acmsdi_call_id Dim request_name As String *64 Dim workspace_count As Long Dim call_id_retr As Long Dim call_id_ref As Long Dim status As Integer call_id_ref = acmsdi_return_pointer(call_id) status = acmsdi_poll(subm_id, ByVal 0&) If status = ACMSDI_REQUEST_EXCH Then status = acmsdi_bind_request_args(subm_id, request_name, workspace_count, call_id_retr) If status = ACMSDI_NORMAL Then 'if all OK and ... If call_id_retr = call_id_ref Then ' ... it;s the call I made ' ' check the request name so we'll know which workspaces we ' are dealing with ' If request_name = "MY_REQUEST" Then >>> Process Request Exchange arguments <<< acmsdi_complete_pp(call_id, TSS_NORMAL) End If End If Else >>> Error processing <<< End If End If

7.4.6 Send Exchange Step Arguments

When acmsdi_poll returns ACMSDI_SEND_EXCH, the client application can issue an acmsdi_bind_send_args to retrieve the write-only arguments. You must declare the memory for all arguments in the client application and pass them by reference.

The first argument, the submitter ID, is a read-only argument and must represent the same submitter for which acmsdi_poll returned ACMSDI_SEND_EXCH. The C-language prototype for acmsdi_send_args follows:

int acms_bind_send_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*/ short *timeout, /*write-optional*/ ACMSDI_CALL_ID **call_id); /*write-optional*/

After the acmsdi_bind_send_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 will be receiving from ACMS. You can receive send forms records from TP Desktop Connector using the acmsdi_bind_send_recs service. You can send receive control text to TP Desktop Connector using the acmsdi_bind_receive_args.

Example 7-6, written in Visual Basic, illustrates:

• Issuance of acmsdi_poll
• Receiving of return code ACMSDI_SEND_EXCH
• Issuance of acmsdi_bind_send_args

Example 7-6 ACMSDI_SEND_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 timeout As Integer Dim call_id_retr As Long Static status As Integer status = acmsdi_poll(subm_id, ByVal 0&) If status = ACMSDI_SEND_EXCH Then status = acmsdi_bind_send_args(subm_id, forms_sess_id, send_rec_id, send_rec_count, timeout, call_id_retr) If status = ACMSDI_NORMAL Then ' if all OK and ... If forms_sess_id = "FORMS_SESS000251" Then ' ... my session >>> Process Send Exchange arguments <<< acmsdi_complete_pp(call_id, FORMS_NORMAL) End If Else >>> Error Processing <<< End If End If