MIAMEX 108: Load module into memory

xcall MIAMEX, MX_USRLOD, idx, fspec$ {,flags, var, count}

MX_USRLOD allows you to create and load a memory module from a file or a variable. Unlike under AMOS, this can be done while running a BASIC program.

Parameters

idx (Num) [out]

will return the index entry number where the module was loaded, or 0 if not loaded. (-1 indicates that the module was already locked into memory.)

fspec$ [in]

must be set to the specification of the file to load into memory. (If the USRMEM_NOFILE flag is specified, then fspec just sets the name of the module in memory.)

flags (Num) [in]

may be set to any sensible combination of the memory module flags. Normally this would only be used to set the USRMEM_LOCKED flag to lock the module in memory, or to specify the USRMEM_NOFILE flag (which is required when loading the module from a variable). See MX_USRMAP for a table of applicable flags.

var (Raw) [in]

When specified in conjunction with the USRMEM_NOFILE flag, the module is loaded directly from the specified variable. This provides a mechanism similar to COMMON.SBR, which has the advantage of not having any particular limits on the module size or name.

count [in]

This parameter makes it easier to load full or partial arrays into a memory module.

When flags contains USRMEM_NOFILE (meaning that the module is to be loaded from contents of the variable var, with fspec$ indicating the desired name of the memory module), then if var is actually an array element, e.g. VAR(1), then count can be specified to indicate the number of elements to load starting with the specified element. For example:

MAP1 ARRAY(70),S,25

XCALL MIAMEX,MX_USRLOD,MIDX,"MYMOD.SYS",USRMEM_NOFILE,ARRAY(1),70

The above would load 70 elements of the array, starting with ARRAY(1) into a memory module named "MYMOD.SYS", whose index number would be returned in MIDX.

Warning #1: It is impossible for the subroutine to know whether the count value you specify is actually valid (i.e. not larger than the array), so the responsibility is yours.

Warning #2: The type of the array must not be F,6 or F,4. (These two types get converted to F,8 by the generall subroutine handler, causing the address of the array seen by the subroutine to not match that seen by the caller.)

Note: count is the number of array elements, not the number of bytes. In the example above, count is specified as 70, which results in 70 elements of the array, or 70 x 25 = 1750 bytes being loaded. In contrast, to read/write more than one array element at a time in MX_USRIO, you would need to specify the number of bytes, not elements. This is a likely error when using both MX_USRLOD and MX_USRIO together.

See the notes under MIAMEX 107 for more information on A-Shell’s user memory architecture.