(F,6) returns a code indicating the result of the operation:
|
Value |
Description |
|
>=0 |
OK, or for opcode 2 indicates control was previously enabled. For opcode 1, if an alphanumeric ctlid parameter is specified, cstatus will return the numeric ID of the new control. |
|
1 |
OK, or for opcode 2 indicates control was previously disabled |
|
-1 |
Add or delete control function failed |
|
-2 |
Button (ctlid or ctext) not found during change or delete operation |
|
-3 |
Out of memory (unable to allocate control storage buffers) |
|
-4 |
Exceeded maximum number of added controls. Note that in A-Shell 1166 of 21 Nov 09, the limit of 600 controls was eliminated; the control table expands as needed, without limit. This value should therefore not occur. |
|
-5 |
No control buffer allocated |
|
-6 |
Illegal opcode |
|
-7 |
Control already exists |
|
-8 |
Control update operation failed |
|
-9 |
Unable to load bitmap or icon file. Note the common error of mismatching the ctype flag (256 or 512) with image file type (BMP or ICO) |
|
-10 |
Incorrect control type for operation |
|
-11 |
No batch in progress |
|
-12 |
Illegal tab request or duplicate batch request |
|
-13 |
Parent dialog not found |
ATE performance notes
If you do not care about the returned cstatus or ctlid, you can specify the cstatus variable as a null string ("") or eliminate it entirely if you do not need any of the other parameters. This prevents the routine from returning any information, eliminating the network turnaround latency (in the case of ATE) that would otherwise accompany each AUI_CONTROL operation. While small, these round-trip delays can add up, so that a screen consisting of many items might take seconds, as opposed to milliseconds, to display. Technically, each control creation operation could fail, but in practice, it is rare, as well as unlikely that your application would have a meaningful recovery planned anyway. So other than the case where you need the returned control ID for future reference, there is little practical value to the returned status. And even in the case of needing the returned control ID, you can eliminate that necessity by supplying an alphanumeric control name in place of the ID; see Control names.
A-Shell 5.1.1132 of 19 Dec 08 adds: to speed up a large sequence of menu operations over a slow ATE link, you can set the STATUS parameter to "" to eliminate the return of the status code. (Same idea as with AUI_CONTROL).
Update note - A-Shell 995.5 of September 07
Previously, ATE would not return any status information (as a bandwidth optimization strategy) if the cstatus parameter was specified as a string (typically "" or NUL_CSTATUS$). This rule has been tightened to allow strings of 2 or more bytes to be treated as valid return variables. This fixes an issue with in SBXINP.SBR involving the disabling of INFLD controls, and perhaps will avoid problems in other applications that mistakenly used a mapped string return variable for the cstatus parameter. Note that if you are counting on the non-return optimization, make sure you use "" or NUL_CSTATUS, or a string mapped as S,1, rather than just any old string variable.
Also note that this fix is on the server side and does not require updating ASHW32.EXE (except when using ATS in which case you need to update the ASHW32.EXE on the server side).