Updated September 2011 (see History)
DIMX anyname (expr1,...,exprn) ,type {,sizeexpr}{,auto_extend}
DIMX is an enhanced version of the venerable DIM statement used to allocate an array at runtime. The enhancements of DIMX over DIM are:
• It accepts optional type and size specifiers rather than being limited to F6 and string with size determined by STRSIZ.
• The element size is evaluated at runtime, whereas with DIM, it is evaluated at compile time.
• It allocates the memory needed out of the system memory pool, rather than from the user partition. Memory used by DIMX is automatically released when the program ends.
• If the AUTO_EXTEND option is specified, the first dimension (first subscript) of the array will be automatically extended as needed whenever an assignment is made to the array.
Examples
DIMX XTDATA(COUNT),S,XTLEN
DIMX XTDATA(COUNT1,A*B,C),B,2
Notes
• DIMX allocations are automatically freed (and memory recovered) when the RUN or SBX in which they are created exits.
• To reset (i.e. delete / free) a DIMX allocation explicitly, use REDIMX to set the subscript extents to zero.
• The contents of a DIMX array (including any extensions to it due to the AUTO_EXTEND feature) are always pre-cleared to nulls.
• The maximum size of an individual DIMX array is determined by the MALLOCLIMIT (default 8MB) option in the MIAME.INI. The limit is tested whenever a DIMX or REDIMX operation takes place, including implicit REDIMX operations triggered by AUTO_EXTEND.
• When an array is automatically extended by the AUTO_EXTEND it will be extended somewhat beyond the amount actually needed for the assignment (on the theory that subsequent expansions are likely to follow). The exact amount of extra expansion is based on a heuristic that is subject to change, but as of build 1191, it consists of the smallest of 110% of the minimum amount required, and 150% of the previous array size. But in no case will the excess expansion (beyond what is immediately needed) be more than 128K. Also see the EXTENT dot function.
• The MALLOC trace option will trace DIMX and REDIMX memory allocations (along with most other memory allocations/de-allocations), making it a useful debugging tool.
• Because there is no support for it under AMOS, DIMX is not normally supported by the /RC compiler switch. However, you can override that (i.e. cause DIMX to be allowed when compiling in /RC mode) by adding the statement "OPTIONS=RC_DIMX" (without quotes) to MIAME.INI. Just be careful to make sure that you don't actually try to execute that statement when running your program under AMOS.
• Global DIMX arrays can be made visible to functions and procedures either via the ++EXTERN mechanism documented in Referencing DIMX Variables or via Dynamic Overlays. Only the latter will work for SBXs.
History
2011 September, A-Shell 5.1.1235
Add direct support for structures. See DIMX and Structures.
2011 March, build 5.1.1209
The value of the first subscript in the DIMX statement can now be zero; previously the minimum was one and zero caused a subscript out of range error.
2010 November, build 5.1.1193
Local non-static DIMX statements are now fully cleaned up on exit from the function or procedure. Previously, the variable descriptor was removed (along with all of the other local stack variables), but the memory handle and allocation remained in effect. With this enhancement, it is no longer necessary to use REDIMX(0...) to "undimx" any DIMX'd arrays at the end of the function. (But it doesn't hurt to perform that step redundantly.) Note that this is purely a compiler adjustment (compiler edit 469, which was included in A-Shell edit 1193), and not a runtime fix.
2010 September, 1192
Added EXTENT dot function and Referencing DIMX Variables capabilities.
2010 August, 1191
Minor refinement in the expansion heuristics used by DIMX with AUTO_EXTEND. When the array needs to be expanded, it is now expanded by a minimum of 150% of the previous array size, or 110% of the size required for the assignment triggering the expansion. But, this is then limited to no more than 128K beyond what would be required for the current assignment. Also, a 128K grace or overage is now added to the MALLOCLIMIT value, to prevent the possibility of the expansion failing because of these heuristics.
2010 August, 1190
Improvements were added in 1190 and 1191 to support its use within recursive SBXs, to add the AUTO_EXTEND feature, and to support removal via REDIMX.
2005 May, 931
DIMX added to A-Shell.
