# MX\_USRIO

> [HTML Version](mx_usrio.htm)

_Updated March 2026; see History_

**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](string.htm.md) 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](num.htm.md))  \[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 |




var  [(BLOB](blob.htm.md) or [String](string.htm.md))  \[in/out\]

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](num.htm.md))  \[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](num.htm.md))  \[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](mx_usrmap.htm.md) for more information on A-Shell’s user memory architecture.

**History**

2026 March, A-Shell 7.0.1784:  restrict the too-verbose ashlog tracing that occurred when the specified module wasn't found. You now need to set the XCALL TRACE to get even minimal tracing of that event, and add the XDEBUG TRACE to trace all of the modules in memory.

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.