Updated July 2008
xcall MIAMEX, MX_USRIO, status, module, opcode, var, {offset}, {bytes}
This function 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 MIAMEX function 108 to load it into memory.)
Parameters
status (F,6) [out]
for read/write operations, will return the number of bytes successfully transferred (0 if the module was not found, negative numbers for errors). For the search operation, returns the position (0 based) if found, else -1 to indicate not found.
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 MIAMEX function 107, 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: 0 for read and 1 for write. 2 and 3 are equivalent to 0 and 1, respectively, except that do automatic unblocking of records, exactly the way disk file records are unblocked when the record size is less than 512 bytes and the SPAN’BLOCKS option is not used. The record size is assumed to be the size of the var parameter, unless the bytes parameter is specified.
|
Value |
Description |
|
0 |
Read bytes |
|
1 |
Write bytes |
|
2 |
Read records |
|
3 |
Write records |
|
4 |
Search for string, case insensitive |
|
5 |
Search for string, case sensitive |
var (Unformatted or String) [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.
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). For opcode 1 and 3, must contain the data to be written. For opcode 0 and 2, receives the data read.
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.
Notes
See the notes under MIAMEX 107 for more information on A-Shell’s user memory architecture.
History
Build 1116 of 967 of 11 June 2008
As of A-Shell 5.1.1116.4, you can also read from a module loaded into user memory by opening it as a sequential file using the MEM: device. For example:
open #ch, "MEM:MYFILE.DAT", input
do
input line #ch, pline
if eof(ch)=0 or pline#"" then
<process pline>
else
exit
endif
loop
close #ch
See discussion of the miame.ini DEVICE statement in the Setup Guide for details on defining the MEM: device.
Build 967 of 27 September 2006
MIAMEX,MX_USRIO now allows you to read and write full or partial arrays. No new parameters are needed. The only change is that now, if the specified var is an array element, then the bytes specified is trusted, even if it exceeds the size of the var parameter. (This is needed, because when a subroutine parameter is specified as array element, e.g. VAR(1), then the size seen by the subroutine is the size of the element, not the size of the entire array.) To transfer read 70 elements worth of data from the memory module loaded in the example shown above in MX_USRLOD (MIAMEX 108), back into the ARRAY, you could use the following:
MAP1 ARRAY(75),S,25
xcall MIAMEX, MX_USRIO, STS, MIDX, 0, ARRAY(1), 0, 70*25
You could also copy from the ARRAY to the memory module in the same way, using opcode 1. The only difference between this and the MX_USRLOD operation is that MX_USRLOD will create the module if it doesn't already exist.