| Previous | Contents | Index |
You allocate certain structures in the client application's memory and pass them by reference to TP Desktop Connector. These structures are:
In standard nonblocking mode, you pass structures by reference as arguments on calls from TP Desktop Connector to client application presentation procedures and completion routines. The pointers to these structures, originally passed to TP Desktop Connector, are passed back to the client routines. The client routines then use these pointers to locate the original structures, which point them to the submitters and calls referenced by the callbacks. Because applications which require forced nonblocking mode do not support callback routines or pointers, different rules apply.
TP Desktop Connector uses the submitter identifier on the service calls to identify the submitter for which the call is issued. For example, the acmsdi_poll service passes the submitter identifier as a read-only argument. In response, TP Desktop Connector returns the latest message type received from the back-end system for that submitter or a return code indicating that no message is available for the submitter. This differs from the acmsdi_dispatch_message service, which dispatches all messages that arrive from the back-end for all submitters.
The services acmsdi_bind_xxxx_args and acmsdi_poll retrieve the call identifier and call context arguments, pointers to structures existing in the client application's memory. Client applications treat these pointers as 32-bit integers; therefore, for these arguments to be useful to the client application, use the acmsdi_return_pointer service to obtain reference pointers (as 32-bit integers) for the structures.
Because data can be moved by memory management routines, you must issue acmsdi_return_pointer calls in the same procedure where you issued the original call. Then compare the values of the arguments against the reference pointers to determine which structure is being referenced. |
Example 7-11, written in BASIC, illustrates the creation of a call identifier on an acmsdi_call_task service call and its later identification during retrieval of the arguments of an enable exchange callback. The example assumes the following:
| Example 7-11 Creation of a Call Identifier |
|---|
Dim subm_id As acmsdi_sub_id ' submitter id structure
Dim call_id As acmsdi_call_id ' call id structure
Dim call_id_ref As Long ' reference to call id
Dim call_id_retr As Long ' call id retrieved from enable
Dim call_ctxt As Long ' call context retrieved using acmsdi_poll
Dim forms_sess_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
Static final_status As Long
call_id_ref = acmsdi_return_pointer(call_id)
task_name$ = "MY_TASK"
appl_name$ = "MY_APPL"
status = acmsdi_call_task(subm_id, ' submitter id structure created at sign-in
ByVal 0&, ' null call options
task_name$, ' task name
appl_name$, ' application name
0&, ' null selection string
status_msg, ' status message return location
0&, ' no workspace count
ByVal 0&, ' no workspace pointer
call_id, ' call id structure
ByVal 0&, ' null final completion status location
0&, ' null completion routine pointer
call_id) ' call context same as call id
If status = ACMSDI_PENDING Then ' If nonblocking call sent to back-end
Do ' loop while the task is executing
status = acmsdi_poll(subm_id, call_ctxt) ' Note: Instead of a Do
if status <> ACMSDI_EXEC ' Loop, the acmsdi_poll
Exit Do ' and code following
End If ' would probably be
' issued in a process
Loop ' kicked off by a timer
If status = ACMSDI_ENABLE_EXCH Then ' If we have an enable exchange step
'
' call to retrieve enable arguments
'
status = acmsdi_bind_enable_args(subm_id, ' submitter id
filespec, ' file specification
formspec, ' forms specification
formversion, ' form version
formprint, ' print file
formlang, ' form language
call_id_retr) ' call id
'
' check call id against out reference id. If they match,
' this enable callback is ours
'
If call_id_retr = call_id_ref Then
>>> Enable processing <<<
forms_sess_id,session_id = "SESSION 12345678" ' session id
status = acmsdi_bind_session_id(subm_id, forms_sess_id) 'send it
acmsdi_complete_pp(call_id, FORMS_NORMAL) ' finish Enable
' processing
End If
ElseIf status = ACMSDI_DONE Then ' If we have task completion
'
' check call context against our call reference id. If it matches, this
' is a completion for our task
'
If call_ctxt = call_id_ref Then
>>> Task completion processing >>>
End If
End If
>>> Handle other statuses from acmsdi_poll <<<
|
The forced nonblocking sample allows you to initiate API calls and to respond to exchange steps as they arrive from the back end, thus demonstrating the use of forced nonblocking API calls. As each exchange step arrives, the sample asks whether or not you want to "bind" the exchange arguments by using one or more API calls. If you choose to bind the arguments, they are retrieved from TP Desktop Connector and displayed in a text box.
TP Desktop Connector does not require that exchange step arguments be bound. You can skip the binding of the basic arguments and bind only exchange step forms records or workspaces, although this sample does not demonstrate this feature. |
The forced nonblocking sample application is written in Visual Basic and contains the files listed in the following table:
| File Name | Description |
|---|---|
| FNBSAMPL.MAK | Visual Basic project file |
| FORM1.FRM | Main form |
| FRMLOGIN.FRM | Form used to login to TP Desktop Connector |
| FRMRECVC.FRM | Form used to determine receive control text values |
| ACMSDI.BAS | TP Desktop Connector global declarations 1 |
| CONSTANT.TXT | Visual Basic global declarations 2 |
| FORMS.BAS | TP Desktop Connector DECforms-style message codes and text 1 |
| MTEXT.BAS | TP Desktop Connector message text initialization procedures |
| NONBLK.BAS | Global declarations specific to this sample application |
Before you execute the sample, follow these steps:
$ @ACMSDI$EXAMPLES_ACMS:FNBTASK |
The main form contains a set of buttons that allows you to activate various API calls. It also contains an options box labeled "Exchange Args", which has two option buttons by which you can choose whether or not you wish to "bind" exchange step arguments.
The main form contains the following text boxes:
The activation buttons are discussed in the following sections.
7.7.3 Starting and Stopping Polling
The polling button starts and stops polling. When polling is active the acmsdi_poll API call is periodically issued in a timer-activated Sub procedure named Timer1_Timer. This button is labeled "Start Polling" if polling is not active or "Stop Polling" if polling is active. In addition, a text box below the button contains the word "Polling" when polling is active. You can start or stop polling at any time using this button. Polling is also automatically stopped and started at appropriate times in the application's procedures.
If polling is not active, task call, task cancel, sign-in and sign-out completions are not detected, nor the arrival of exchange steps. If the application appears to stall, it may be because polling is not active. If this is the case you can click this button to start polling.
When designing your own application, do not allow the user to start and stop polling but rather, automatically start and stop polling in the application's procedures. When polling is active, hide the polling activity from the user. For example, do not get into a polling loop which continuously displays the fact that there is no active task. |
To sign into TP Desktop Connector, click the button labeled "Sign In". The sample displays the Sign In form (FRMLOGIN.FRM) allowing you to enter the user name, password, and host node name. There is also an options box labeled "Select Server Type". This options box is intended for future use when ACMSxp systems are supported. However, for now you may select only ACMS servers. The "Cancel" and "OK" buttons allow you to complete the sign-in attempt or to cancel the sign-in attempt if you change your mind.
If you choose to complete the sign-in attempt, the application issues the acmsdi_sign_in API call. The Sign-In form is hidden and the application waits until acmsdi_poll recognizes the sign-in completion. At that time, an acmsdi_complete_call API call is issued to retrieve the sign-in call status. The code for this call can be found in the SigninComplete procedure.
A dialog box is displayed to inform you of the success or failure of
the sign-in attempt. If the dialog box does not appear in a reasonable
amount of time, it may be because polling is stopped. If this is the
case, simply click the button labeled "Start Polling".
7.7.5 Calling the ACMS Task from Sample
After you have successfully signed in, you can call the ACMS task, "FNBTASK", by clicking the "Call Task" button. The text box below this button contains the words "Task Executing". The sample application issues an acmsdi_call_task API call in the cmdCallTask_Click procedure.
Dialog boxes are displayed announcing the arrival of exchange steps.
Exchange step arrivals are detected by the acmsdi_poll service, so
polling must be active when the "Call Task" button is clicked. Examine
the code found in the Timer procedure of the Timer1 object
(Timer1_Timer) to see how polling is handled for this sample
application.
7.7.6 Forced Nonblocking Exchange Steps
The ACMS task, FNBTASK, issues three DECforms-style exchange steps; transceive, send and receive, in that order. Because these are DECforms-style exchanges, the first exchange step to actually arrive for a given signed-in session is an enable exchange. If this were an actual DECforms session, this exchange provides the information DECforms needs to initialize the first form. However, in the visual basic environment, enable exchanges are often ignored.
Exchange steps in this sample are acknowledged using the F1 and F2 keys. The KeyUp procedure of the Form object (Form_KeyUp) contains the code which responds to the F1 and F2 keys.
TP Desktop Connector does not require that you issue any of
the various "binds" which are used to retrieve and send exchange step
arguments. However, the acmsdi_complete_pp call is required to signal
the end of exchange step processing. For this sample, the code which
issues this call is found in the CompleteExchange procedure.
7.7.6.1 Forced Nonblocking Enable Exchange Step
After clicking the OK button, which announces the arrival of the enable exchange, the Message text box contains instructions as to the next step you can take. You must select "Bind" or "Continue" from the Exchange Args options box and press the F1 key. If you select "Bind", the enable exchange arguments are read from TP Desktop Connector with the acmsdi_bind_enable_args call, and they are displayed in the Arguments text box. If you select "Continue", acmsdi_bind_enable_args is not issued and the application proceeds directly to the transceive exchange step.
If you choose to bind the enable arguments, they are displayed in the Arguments text box. Instructions are displayed in the Messages text box. The next step is press the F2 key.
You then see a dialog box, which announces that a Session Identifier
has been sent to TP Desktop Connector. This session identifier
is useful if your application is written to handle DECforms
sessions. The session identifier is sent with an acmsdi_bind_session_id
call. The code that issues this call is found in the Form_KeyUp
procedure.
7.7.6.2 Transceive, Send and, Receive Exchange Steps
The code for the transceive, send and receive exchanges is essentially the same; the differences being primarily in the number and types of arguments and forms records exchanged. The arrival of each exchange step is announced by the display of a dialog box. After the dialog is dismissed, instructions are displayed in the Messages text box. As was the case with the enable exchange, you are asked to choose whether or not you want to bind the exchange arguments by choosing "Bind" or "Continue" from the Exchange Args options box. Then you are instructed to press F1. Exchange arguments are displayed or not, depending on your choice. The API calls for retrieving the arguments are:
After pressing F1, the exchange arguments are displayed in the Arguments text box if you chose to bind them. Whether you choose to bind the arguments or not, the next set of instructions requests that you press F2 to continue. If you chose to bind the arguments, the send records are displayed next, including the send control text. The TP Desktop Connector API call issued to retrieve the send control text and send forms records is acmsdi_bind_send_recs, the code can be found in the ShowSendRecs procedure.
In either case, pressing F2 eventually causes the Receive Control Text form (FRMRECVC.FRM) to be displayed. For this ACMS task, the receive control text is used to instruct the task to sleep for 5 seconds or to return immediately. If "Sleep" is chosen, the delay may be used to attempt to cancel the ACMS task using the Cancel Task button.
After the Receive Control Text form has been dismissed, the sample
application completes the exchange step by calling
acmsdi_bind_receive_recs to send receive control text and receive forms
records back to ACMS and finally, by calling
acmsdi_complete_pp. The code for these calls can be found in the
CompleteExchange procedure.
7.7.7 Task Completion
After the last exchange step has completed, the acmsdi_poll service recognizes the task completion which arrives from the back end unless you decide to cancel the task (See Section 7.8.9). The CalltaskComplete procedure is given control. This procedure issues an acmsdi_complete_call API call to retrieve the final completion status and task argument workspaces from the back end. A dialog box is displayed showing the final completion status. After dismissing the dialog box, if the task completed normally, the task argument workspaces sent from the ACMS task are displayed in the Messages text box.
You can now either reexecute the task, perhaps trying some different
options, by clicking the Call Task button or sign out by clicking the
Sign Out button.
7.7.8 Signing Out
To sign out of TP Desktop Connector, click the button labeled "Sign Out". The application then issues the acmsdi_sign_out API call. The application waits until acmsdi_poll recognizes the sign-out completion. At that time, an acmsdi_complete_call API call is issued to retrieve the sign-out call status. The code for this call can be found in the SignoutComplete procedure.
A dialog box is displayed to inform you of the success or failure of
the sign-out attempt. If the dialog box does not appear in a reasonable
amount of time, it may be because polling is stopped. If this is the
case, simply click the button labeled "Start Polling".
7.7.9 Cancelling the Task
After dismissing the Receive Control Text form (see Section 7.8.6.2), the current exchange step is completed and, if you chose to have the ACMS task "sleep" for 5 seconds, you can use that delay to cancel the task. Click the Cancel Task button. The application issues an acmsdi_cancel API call in the cmdCancelTask_Click procedure.
A dialog box is displayed to tell you that the task was or was not successfully cancelled. After dismissing that dialog box a second dialog box is displayed to show the final task completion. As in any API service completion the acmsdi_poll service recognizes both the cancel and the task completion.
Because the task cancellation is recognized as a task failure, the Messages text box shows a set of task failure messages and the actual status message received from ACMS:
Task was cancelled by task submitter |
This represents a normal completion for a cancelled task. However, because it represents a task failure, polling is automatically stopped. Therefore, to proceed with another task call or a sign out call, start polling by clicking the Start Polling button. This is not a recommended way to write your application. As stated earlier, polling should be transparent to the end user. However, for this sample application, this technique illustrates the importance of keeping polling active in order to detect call completions and exchange steps.
| Previous | Next | Contents | Index |