Note: Batch operations are now deprecated, as the original motivation (improved ATE performance) has been satisfied in a simpler way by using numeric Control names. The remainder of the discussion below is retained here for historical purposes only.
CTLOP_RSA (opcodes 8 and 9) offer increased efficiency for creating many controls at a time, and may be of interest when the application server and workstation are not the same machine. In that environment, for each control created, the application server sends the request to the workstation, which creates the control and sends back the control ID and status. Although the amount of information transferred is minimal, the delay introduced by the server having to wait for a response to each command before issuing the next can add up to noticeable delays, particularly on a slow network.
There are two general techniques for minimizing those delays: activating the "ATE Reverse Channel" (described elsewhere), and creating controls in a batch. When controls are created in a batch, the return information (ID and status) for each control is buffered on the workstation until the batch is complete, after which it sends all the return information in a single packet. The main drawback of this approach is simply that it takes two extra steps for each batch – one command to start the batch and another to finish it.
To start a batch, use opcode 8, as follows:
xcall AUI, AUI_CONTROL, CTLOP_SBCH, cstatus
The normal return cstatus is 0. If a batch has already been started, cstatus will be set to –12. Other values all correspond to errors.
Once the batch is started, you can proceed to issue commands to create or query controls as you normally do, but do not bother checking for returned ctlid or cstatus values, as they are buffered by the ATE client. (You do need to specify valid ctlid and cstatus parameters, just as if you were getting those parameters back on every call; otherwise the return status is not added to the buffer for later return.)
To complete the batch and retrieve the buffered values, use opcode 9:
COUNT = <maximum number of controls in batch>
XCALL AUI, AUI_CONTROL, CTLOP_EBCH, CSTATUS, COUNT, ID(1), CB(1)
If CSTATUS # <number of controls requested> then goto Error
The parameters should be mapped something like the following:
MAP1 ID(20),B,2 ! array of control IDs (sized large enough for the batch)
MAP1 CB(20),B,1 ! array of status codes (or checkbox values)
MAP1 CSTATUS,F,6 ! returns number of controls actually created in batch
MAP1 COUNT,B,2 ! number of controls expected (max)
The count parameter must be set to the maximum number of controls in the batch (and no larger than the arrays.) Typically you would set this to the actual number of controls you attempted to create in the batch, although it might also be set to the maximum size of the arrays. (It just sets an upper limit on the amount of information returned.)
cstatus will be updated to the actual count of controls created in the batch. If it does not agree with the number you tried to create, then there was a problem.
The id() array receives the ctlid values of the controls created in the batch.
The cb() array receives the status codes that would have otherwise been returned in the cstatus parameter for each control creation operation. Note that it must be mapped as an array of B,1 (as shown above), so negative cstatus values will appear as 255 (-1), 254 (-2), etc. (Mainly you only care if the status is 0 or not.)
Note that you normally specify the first element of each array in the parameters passed to the subroutine as shown in the example above. But if you have one large array of control Ids, yet for some reason you use multiple batches to create your controls, you could specify a different starting value for a subsequent batch, e.g. cb(10) instead of cb(1), as long as the array is big enough.
As an example of using a batch, we will recode the example given for opcode 5 above, this time using a batch operation to create the checkboxes, and another to query them. See the sample program TSTBMN in SOSLIB:[907,24] for a complete working version of this logic.
MAP1 CID(7),B,2 ! control Ids for the checkboxes
MAP1 CB(7),B,1 ! chkbox state (0=unchecked, 1=checked)
MAP1 OPTDLGID,B,2 ! ID of dialog box
MAP1 STATUS,F,6
MAP1 NOSTATUS$,S,1,"" ! use when we do not care about status or ID
CREATE'DIALOG:
OPTDLGID = 0
xcall AUI, AUI_CONTROL, CTLOP_INFO,OPTDLGID, "Eventwait Option Flags", MBST_ENABLE, MBF_DIALOG + MBF_SYSMENU, "", "", STATUS, 2, 2, 11, 23
if OPTDLGID = 0 then goto ERROR'OUT
!(assume that CB(7) values have been initialized appropriately)
! Start a batch:
xcall AUI, AUI_CONTROL, CTLOP_SBCH, STATUS
if STATUS # 0 goto ERROR'OUT
xcall AUI, AUI_CONTROL, CTLOP_INFO, CID(1), "Start on next control (1)", MBST_ENABLE, MBF_CHKBOX + MBF_LFJUST, "", CB(1), STATUS, 2, 3, 2, 21, -2, -2, 0, 0, "", "", OPTDLGID
xcall AUI, AUI_CONTROL, CTLOP_INFO, CID(2), "Do not wait for event (2)", MBST_ENABLE, MBF_CHKBOX + MBF_LFJUST, "", CB(2), STATUS, 3, 3, 3, 21, -2, -2, 0, 0, "", "", OPTDLGID
xcall AUI, AUI_CONTROL, CTLOP_INFO, CID(3), "Do not wrap (4)", MBST_ENABLE, MBF_CHKBOX + MBF_LFJUST, "", CB(3), STATUS, 4, 3, 4, 21, -2, -2, 0, 0, "", "", OPTDLGID
xcall AUI, AUI_CONTROL, CTLOP_INFO, CID(4), "Do not set focus (8)", MBST_ENABLE, MBF_CHKBOX + MBF_LFJUST, "", CB(4), STATUS, 5, 3, 5, 21, -2, -2, 0, 0, "", "", OPTDLGID
xcall AUI, AUI_CONTROL, CTLOP_INFO, CID(5), "Allow numeric input (16)", MBST_ENABLE, MBF_CHKBOX + MBF_LFJUST, "", CB(5), STATUS, 6, 3, 6, 21, -2, -2, 0, 0, "", "", OPTDLGID
xcall AUI, AUI_CONTROL, CTLOP_INFO, CID(6), "Descend into child groups (32)", BST_ENABLE, MBF_CHKBOX + MBF_LFJUST, ", CB(6), STATUS, 7, 3, 7, 21, -2, -2, 0, 0, "", "", OPTDLGID
xcall AUI, AUI_CONTROL, CTLOP_INFO, CID(7), "Allow focus on siblings of parent control (64)", BST_ENABLE, MBF_CHKBOX + MBF_LFJUST, ", CB(7), STATUS, 8, 3, 8, 21, -2, -2, 0, 0, "", "", OPTDLGID
! finish the batch
COUNT = 7 ! number of controls in the batch
Xcall AUI,AUI_CONTROL, CTLOP_EBCH,STATUS,COUNT,CID(1),CB(1)
If STATUS # 7 then goto ERROR'OUT
! Add the buttons (they could have been part of the batch, but
! here we decided to leave them out because we do not need to
! reference then directly later anyway)
xcall AUI, AUI_CONTROL, CTLOP_INFO, 0, "OK", BST_ENABLE, MBF_BUTTON + MBF_KBD, %VK_F2%", "", NOSTATUS$, 9, 4, 9, 10, -2, -2, 0, 0, "", "", OPTDLGID
xcall AUI, AUI_CONTROL, CTLOP_INFO, 0, "Cancel", BST_ENABLE, MBF_BUTTON + MBF_KBD, %VK_ESC%", "", NOSTATUS$, 9, 13, 9, 19, -2, -2, 0, 0, "", "", OPTDLGID
To query the checkboxes later, we can also use a batch operation:
xcall AUI,AUI_CONTROL, CTLOP_SBCH, STATUS ! start a batch
If STATUS # 0 goto ERROR'OUT
COUNT = 7 ! send 7 query commands...
For I = 1 to COUNT
xcall AUI, AUI_CONTROL, CTLOP_QRYCB, CID(I), "", 0, "", "", STATUS
Next I
xcall AUI,AUI_CONTROL,CTLOP_EBCH,STATUS,COUNT,CID(1),CB(1) ! finish batch
If STATUS # COUNT then goto ERROR'OUT
! CB(I) array is now set with the status of each checkbox