(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.
History
2008 December, A-Shell 5.1.1132: 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.
2007 September, A-Shell 995: Allow strings of two or more bytes to be treated as valid return variables.