Please enable JavaScript to view this site.

A-Shell Consolidated Reference

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