A-Shell Reference

Zoom Window Out
Larger Text | Smaller Text
Hide Page Header
Show Expanding Text
Print Topic
Share This Topic
Save Permalink URL

MX_DYNSTRUCT

Reviewed April 2024

MX_DYNSTRUCT (MIAMEX 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}

xcall MIAMEX, MX_DYNSTRUCT, DYNOP_BIND, status, dsname$, ds

xcall MIAMEX, MX_DYNSTRUCT, DYNOP_INFO, status, ds, fields, flddefs(1)

xcall MIAMEX, MX_DYNSTRUCT, DYNOP_INFO, status, dsname$, fields, flddefs(1)

xcall MIAMEX, MX_DYNSTRUCT, DYNOP_COPY, status, dssrc, dsdst

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

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()

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.

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.

Please enable JavaScript to view this site.

A-Shell Reference