MIAMEX 192: Dynamic Structures

MIAMEX function MX_DYNSTRUCT (192) implements A-Shell's dynamic structures. Note that there is a lengthy discussion of Dynamic Structures in "Development Topics."

xcall MIAMEX, MX_DYNSTRUCT, DYNOP_DEF, status, src$, fields, stsize, dsname$ {,errmsg$,workareak}

This MIAMEX subfunction provides various utilities related to dynamic structure operations, according to the specified opcode:

Note the existence of the wrapper functions in the SOSFUNC library module. In general these are preferred over the direct MX_DYNSTRUCT calls because they provide a degree of isolation between the internals of the implementation (which may be subject to change) and the application. In some cases the wrapper functions also provide additional convenience by taking care of details.

Opcode from ashinc: dynstruct.def	Description	Wrapper Function from sosfunc:fndynst.bsi
DYNOP_DEF (1)	Define (aka compile) a dynstruct. See History below.	Fn'Dynst'Define()
DYNOP_BIND (2)	Bind a defined dynstruct to a dynstruct variable	Fn'Dynst'Bind()
DYNOP_INFO (3)	Retrieve layout info for a dynstruct definition or for a bound dynstruct variable	Fn'Dynst'Get'Def'By'Name() Fn'Dynst'Get'Def'By'Instance()
DYNOP_COPY	Copy a bound dynstruct variable to a previously un-bound dynstruct variable.	Fn'Dynst'Copy()

Parameters

status (Signed Num) [in]

Returns status of the operation, according to the following table:

Value	Description
0	Success
-1	Illegal opcode (DYNOP_xxx)
-2	No results to process
-3	Out of memory
-4	Too few parameters
-6	Fields value, i.e. flddefs() array extent, too small to hold all results
-7	Bad flddefs() array parameter
-8	Dynstruct definition corrupt
-9	Unable to locate named structure definition
-10	Parameter not a dynstruct
-11	Dynstruct uninitialized
-12	Compilation error

fields (Num) [in/out]

For DYNOP_DEF, returns the number of fields in the defined structure. Note that this includes a field for the overall structure itself. For DYNOP_INFO, caller must set fields to the extent of the flddefs() array. On return, it will contain the number of fields in the structure, which may be more than the size of the flddefs() array, in which case status will be -6, but the array will be filled to the size set by the original value of fields.

stsize (Num) [out]

Returns the overall size of the defined structure.

src$ (String) [out]

A string or file containing or referencing the target DEFSTRUCT (per dsname$), along with all the DEFINEs, DEFTYPEs, and other DEFSTRUCTs on which the target depends. There are three sub-cases:

• src$ contains the source code as one large string variable, with each line terminated by a chr(10). This allows building the source DEFSTRUCT dynamically at runtime.

• src$ is a filespec (of the file containing the source code containing the target DEFSTRUCT). To distinguish this case from the prior one, precede the filespec with "@", e.g. src$ = "@devlib:recmaps.def"

• if src$ = "", the DEFSTRUCT is assumed to be embedded into the current RUN file. See History below and Structure Definition Embedding for details.

Note that for the first two cases, any other source code not part of or prerequisite to the target DEFSTRUCT will be ignored. So it can be used to extract DEFSTRUCT definitions from any source code (including nested ++includes) that can otherwise be compiled.

dsname$ (String) [in]

Name of the dynamic structure, which is the same as the name of the DEFSTRUCT used to define it, not to be confused with the name of the dynstruct variable to which it will eventually be bound. Determines which DEFSTRUCT within the source (src$) contains the actual dynamic structure definition. For DYNOP_BIND, it contains the name of a previously defined structure to bind to the specified dynstruct variable.

errmsg$ (String) [out]

will return the text of any error that occurs during the process of compiling the definition.

ds, dssrc, dsdst (Dynstruct) [in/out]

For DYNOP_BIND, this is the variable to be bound to the definition. For DYNOP_INFO, this is a previously bound dynstruct variable from which the routine will retrieve the definition. For DYNOP_COPY, these are the source and destination dynstruct variables. The source (dssrc) must have been previously bound to a definition. The destination (dsdst) will be bound by the function to the same definition, and the content of dssrc will be copied to dsdst.

flddefs (ST_FLDDEF) [out]

The DYNOP_INFO call returns an array describing each field of the specified structure. Unless you want only the first field, you must specify the first element of the array in the parameter list, i.e. flddefs(1).

Note that subroutine is not able to auto_extend the array; it is up to the caller to dimension it appropriately and to then specify the actual extent in the fields parameter. The routine will fill out the array up to the smaller of the actual number of fields in the structure definition, or the number of elements passed from the app in the fields parameter. If the return information is truncated due to fields being too small, status will be set to -6, but fields will be returned with the total # of fields in the structure, allowing the application to redimension the array and call the function again if desired.

Note that the first entry in the returned array describes the entire structure, rather than being a traditional structure member.

To retrieve just the name of the structure definition to which a dynstruct variable is bound, you can pass the flddefs parameter as a scalar, or a single-element array. The structure definition name will be returned in both the name and deftyp members of the first element.

workareak (Num) [in]

requested work area size in kilobytes, default is 2048.

2022 February, A-Shell 6.5.1711: MX_DYNSTRUCT enhancement: the DYNOP_DEF call now supports the ability to retrieve the structure definition directly from the RUN file, provided it has been embedded. To indicate that you want to retrieve the definition from the current RUN file, set the src$ parameter to "", for example: xcall MIAMEX, MX_DYNSTRUCT, DYNOP_DEF, status, "", fields, stsize, dsname$

2021 October, A-Shell 6.5.1707, compiler edit 952: Several changes: The default amount of work area memory allocated when defining (compiling) a dynamic structure has been increased from 128K to 2M. A new optional parameter, workareak, has been added to allow the caller to specify more than the default amount of memory when defining a dynamic structure. The routine now properly returns status -3 for the out-of-memory condition, allowing the caller to try again with an explicitly larger workarea.

2019 April, A-Shell 6.5.1659,compiler edit 898: Compiler refinement, edit 898: MX_DYNSTRUCT now allows DEFTYPE aliases for implicitly sized X variables. There were previously allowed, but the DEFTYPE name was lost during the runtime compilation.