xcall MIAMEX, MX_USRIO, status, module, opcode, var {,offset, bytes}
MX_USRIO (MIAMEX 111) allows you to read and write directly to a memory module. This is a relatively advanced technique that might be useful either to maximize performance in an I/O intensive operation, or to gain the equivalent functionality of a dynamically allocated unformatted variable. (For the latter, it would be necessary to first create a dummy disk file of the desired size, then use MX_USRLOD to load it into memory.)
Parameters
status (F6) [out]
returns status of the operation, per the following table:
Value |
Description |
|---|---|
-99 |
Invalid opcode |
-2 |
var parameter is an array with layout insufficient to transfer bytes |
-1 |
module not found (when module parameter is a string); for numeric module, indicates nothing loaded into that slot. |
0 |
module number out of range (when module parameter is a number) |
>0 |
For read/write operations: number of bytes transferred. For search operations: offset to start of match |
module (String or Num) [in]
must be set to the name or index number of the module to access. If it is a string, it is interpreted as the name and extension of the module (e.g. "EMAILX.SBX"). If it is a numeric parameter, it is interpreted as the index number of the module. (The index number can be obtained from the module name and extension using MX_USRMAP, and its subsequent use would be more efficient by eliminating the need to scan the memory module list to locate the module by name on each access.)
opcode (Num) [in]
indicates the operation per the following below.
Value |
Description |
|---|---|
0 |
Read bytes |
1 |
Write bytes. See Notes, below. |
2 |
Read records. See Notes, below. |
3 |
Write records |
4 |
Search for string, case insensitive |
5 |
Search for string, case sensitive |
For opcodes 1 and 3, must contain the data to be written. For opcodes 0 and 2, receives the data read. For opcode 4 and 5, must be set to the string to search for. Note: do not use a dynamic variable in read modes. If var is an array, specify the first element to be referenced, i.e. var(1). The routine will determine the element size and extent automatically, and the transfer may extend from that element to the end of the array, depending on bytes.
offset (Num) [in]
specifies the starting offset from the beginning of the memory module. If opcode is 0 or 1, the offset is assumed to be in bytes. If opcode is 2 or 3, it is in records (of size defined by the size of the var parameter, or the value of the bytes parameter, if specified). Note that the first byte or record is at offset 0, not 1..
bytes (Num) [in]
indicates the number of bytes to read or write. In record mode (opcode 2 and 3) it may be omitted, in which case the size of the var parameter will determine this.
Comments
Opcodes 2 and 3 are like 0 and 1 except they treat the data as if it were 512-byte-blocked, i.e. organized like disk file records when the SPAN'BLOCKS option is not used. If the record length does not divide evenly into 512, and the data was loaded either from an array or from a file using the SPAN'BLOCKS, then you will need to use opcodes 0 and 1 instead, e.g. to read the Nth record using opcode 0, set offset = sizeof(var) * (N-1). Other differences with the record-oriented opcodes are that the bytes parameter becomes optional (defaulting to the the size of the var parameter), and the offset parameter unit becomes records rather than bytes.
See the notes under MX_USRMAP for more information on A-Shell’s user memory architecture.
History
2023 July, A-Shell 6.5.1734: opcode 0 was failing to find the specified module by name if it was in the very first position in the module cache. It now logs a detailed trace to ashlog in the case of failure.
