Updated July 2008

xcall MIAMEX, MX_USRIO, status, module, opcode, var {,offset, bytes}

MX_USRIO 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  (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.

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.

var  (Raw 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). 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.

Notes

Opcodes 3 and 4 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

2008 June, A-Shell 5.1.1116:  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 DEVICE system parameter for details on defining the MEM: device.

2006 September, A-Shell 4.9.967:  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 70 elements worth of data from the memory module loaded in the example shown above in MX_USRLOD, 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.