804.1.1. DEL.LIT 2.1(104) fixes a couple of problems, including an infinite loop with DEL *.*.
804.1.2. (WINDOWS) A problem with A-Shell immediately closing down when launched on a W2K server unless OPTIONS=NTTS has (hopefully) been resolved.
804.1.3. (UNIX) Several minor internal improvements in the inter-job communication system which clean up problems using FORCE. (It wasn't previously working when the target job was in tcki or timed input modes, and worked intermittantly when the target job was actively receiving messages from another job (such as via CHAT or JSTAT.)
804.1.4. Fix an obscure bug in XPAINT.SBR which caused occasional characters in screens to be blanked out.
804.1.5. Increase maximum TCP packet size in TCPCLI.SBR and TCPSRV.SBR from 2000 to 4096 bytes.
804.0.1. Add an option to GET.SBR to input logical lines (terminated with LF) by setting the BYTES'REQUESTED parameter (param #3) to -1. In this mode, it will exit as soon as it sees an LF character. It will throw away both CR and LF, but it will add them to the BYTES'RETURNED count. (This is the only way you will be able to tell if a CR or CRLF was actually received instead of the field timing out or the file ending with no terminator on the last line. It is also the only way to tell the difference, when input from a file with no timeout, between a blank line and EOF.)
For cases where you want to terminate on CR rather than LF, you can set BYTES'RETURNED to -2.
804.0.2. User memory "Version 1.0" implemented. This includes AMOS-like behavior for LOAD, MAP, DEL, and SAVE, as well as auto-caching of SBX subroutines, and dynamic allocation of memory as needed to load programs. It also includes a facility for reading and writing directly to user memory at the record or byte level. It does not, however, include an implementation of the MEM: driver (i.e. the device "MEM:" continues to be act just like any other disk device.)
The updated and new LIT commands are listed below, followed by numerous details about the operation and configuration of the new memory architecture:
LOAD.LIT 2.1(104)
MAP.LIT 2.0(104)
DEL.LIT 2.1(103)
SAVE.LIT 1.0(100) (new)
The current limit on the NUMBER of modules loaded into user memory is 32. There is no specific limit on the combined SIZE of the modules, except that you can specify a limit on the amount of memory used for caching subroutines, by adding a third parameter to the MEMORY statement in the MIAME.INI, whose complete syntax is now:
MEMORY=<PARTITION> {,<SBXMEM> {,<CACHE-LIMIT>}}
PARTITION specifies the size of each job's main user memory partition. Previously this was equivalent to user memory under AMOS in that it was used to load programs, subroutines, and allocate variables and other temporary storage. Now, it is only used for variable allocation and other temporary storage. Programs themselves are loaded into one of the 32 dynamically allocated slots that make up "user memory". Consequently, the PARTITION value does not need to be as large as before. Thus, if you don't specify the CACHE-LIMIT parameter (which would be an indication that you were not aware of the new memory architecture), A-Shell will automatically cut your PARTITION value by a third. For example, consider the following memory specification (in MIAME.INI):
MEMORY=900K
The above will result in a work area allocation of 600K (2/3 of the requested 900K.) However, if you specify:
MEMORY=900K,500K,300K
then you will get your 900K work area, as before.
Note that the memory required by a running program is primarily determined by the size of the MAP statements. Other than calculating it by hand, the best way to find out how much memory you need is by using the MEM(0) function, which returns the amount of free memory at that time.
Also note that a suitable memory work area size should probably allow for the largest commonly used SBX subroutine (or routine called via XCALL AMOS) to be loaded. A-Shell will allocate an additional work area for SBX and XCALL AMOS-called modules if there is not enough room in the main work area, but this is slightly less efficient than just sharing the main work area.
Finally, note that two of the largest common memory hogs, VUE and INMEMO, allocate their own dynamic storage independent of your main work area, so there is no need to worry about them when determining an appropriate size for your work area.
The SBXMEM parameter specifies the minimum amount of free memory needed for executing an SBX subroutine. As stated above, if there is at least that amount of memory free within the main PARTITION at the time an SBX subroutine is called, then the PARTITION free memory is used directly. Otherwise, a separate, dynamic allocation will be made. This logic hasn't changed from before, except that as with the PARTITION, the SBXMEM space can now be somewhat smaller because it does not actually hold the SBX code. Consequently, as with the PARTITION value, if you don't specify the CACHE parameter, A-Shell will cut the value you specify by 1/3. (If you don't specify SBXMEM at all, the default is now 256K, down from the previous 360K default. If you specify 0, then there is no default and SBX routines will always use only what is available in the main PARTITION.) See the notes in UPDATE.TXT for further information about the way SBX routines operate (search for "SBX").
See the notes on TRACE=USRMEM and TRACE=MALLOC below for further information on analyzing whether special allocations are being made for subroutine calls.
CACHE-LIMIT is an optional new parameter to the MEMORY command, which specifies the amount of memory available for automatic caching of frequently used subroutines. The "LRU" (least recently used) principle is used, in conjunction with a 10 minute timeout, to do "housecleaning". That is, when attempting to cache a new module, any module that hasn't been accessed within the last 10 minutes will be deleted, and there still isn't room for the new module, the least recently used module is deleted. Auto-cached modules act just like modules that were loaded with the LOAD command, except that the latter do not count against the CACHE-LIMIT size, and are not subject to "housecleaning" (i.e. can only be deleted explicitly with the DEL command.)
The default value for CACHE-LIMIT is 200K. If you don't want any caching, you must explicitly specify 0. Note that memory is allocated and freed as needed for caching, so if you don't call any SBX routines, you won't be wasting any memory. Also note that this limit is treated as a suggestion, rather than a fixed limit. In practice, it means that if we are about to auto-cache a module and the existing cached modules exceed the CACHE-LIMIT value, then we force the one least recently used to be discarded before loading the new one.
(See TRACE=USRMEM below for information on monitoring the effect of your CACHE-LIMIT.)
804.0.3. The new SAVE.LIT command has been introduced to allow you to save a module from user memory back to disk. Use SAVE /? to see the syntax. Note that you can only specify a file name and extension, so the file will be saved in the current ppn.
There are a couple of points to note about SAVE.LIT: First, the most likely reason for using it would be to save some kind of data module that has been changed in memory. Since the MEM: device driver has not yet been implemented, the only way you could change a data module in memory now is via the expanded XCALL MIAMEX,81 (which see below.)
The second point is that SAVE does not allow you to save program modules (i.e. those with extensions of RUN, LIT, or SBX.) Aside from being of rather dubious utility, it would be downright dangerous to allow this because A-Shell modifies the structure of these programs when they are loaded into memory, in order to make them run more efficiently.
804.0.4. Five new MIAMEX functions have been added relating to memory modules:
Search user memory:
XCALL MIAMEX, 107, SLOT, NAME, SIZE{,FLAGS {,ADDR}}
Load file into user memory:
XCALL MIAMEX, 108, SLOT, FSPEC
Delete module from user memory:
XCALL MIAMEX, 109, SLOT, NAME
Save memory module to disk:
XCALL MIAMEX, 110, STATUS, NAME
Read/write directly to/from memory
XCALL MIAMEX, 111, STATUS, MODULE, OP, VAR {,OFFSET {,BYTES})
Function 107 (MX'USRMAP) is analogous to the AMOS SRCH monitor call, allowing you to locate modules in user memory. To use, set SLOT to 0 (or leave it at the previously located SLOT in order to search forward from a position other than the start of user memory.) It will be returned as the slot number (1=first) of the located module, or 0 if not found. Set NAME to the name.ext of the module to locate, or blank to locate the first module after the specified SLOT #. It will be returned with the name of the located module. SIZE will return the size in bytes. FLAGS will return flags relating to the module status:
1 (USRMEM'AUTOLOAD)
Module was auto-loaded and will be kept in cache
2 (USRMEM'LOCKED)
Module is locked. Currently this only happens if it is running, although we may add a switch to LOAD to force this flag on.
4 (USRMEM'NOCACHE)
Module will be discarded the next time we load another module. This is currently set automatically for RUN and LIT modules that are auto-loaded.
The ADDR parameter will be set to the address of the memory module. This would be needed in order to use the expanded XCALL MIAMEX,81 function to read or write a memory module directly (see below.)
Note that the MAP.LIT command would in most cases be used instead of this XCALL.
Function 108 (MX'USRLOD) loads a module into user memory. (Note that unlike the case under AMOS, you can do this within a BASIC program.) The FSPEC argument is a normal AMOS filespec of the module to load. The SLOT argument will be returned <=0 if unsuccessful, or else it will indicate the slot number that the module was loaded into. Note that if a module of the same name.ext already exists in user memory, it will be deleted and the new one will replace it (unless it is locked, in which case the operation will fail.) Note that in most cases, the LOAD.LIT command would be used instead of this XCALL.
Function 109 (MX'USRDEL) deletes a module. NAME is the name.ext of the module to delete. (It may contain dev: and [p,pn] but they will be ignored.) SLOT will return the deleted module's slot number if successful, or 0 for not found, or <0 for an error. Attempting to delete a locked module is an error. Note that you would normally just use the DEL.LIT command instead of this XCALL.
Function 110 (MX'USRSAV) saves a module. NAME is the name.ext of the module to save. STATUS will return the number of bytes written to disk if successful, or 0 if the module is not found, or <0 for an error.
Function 111 (MX'USRIO) allows you to read/write a module directly in memory. STATUS will return the number of bytes transferred, which should be equal to the BYTES parameter or the size of the VAR parameter if the operation is successful. 0 indicates the module was not found. Other errors are indicated by negative numbers.
MODULE may be the module's name.ext, or for greater efficiency you can set it to the module's slot number (returned from a previous XCALL MIAMEX,MX'USRMAP or MX'USRLOD operation.)
OP is 0 to read, 1 to write, 2 for record-oriented reading, and 3 for record-oriented writing. For OP's 0 and 1, you will specify the byte offset from the start of the module in the OFFSET parameter. For OP's 2 and 3, you will specify the record # (first record is 0), and A-Shell will automatically handle the blocking if the record size is not a multiple of 512 and the file was not created using span'blocks.
VAR is the raw data to read or write. It will be handled as though it were unformatted, regardless of the data type . (i.e. just like a file read or write operation.)
OFFSET is the offset in bytes from the start of the module where the reading or writing will begin (for OP 0 and 1), or the record number (for OP 2 and 3). The default is 0.
BYTES is the number of bytes to read or write. If BYTES not specified, it will default to the size of VAR. The number of bytes transferred will be limited to avoid overrunning the end of VAR or of the memory module.)
Note that the combination of this function and the ability to load data files into memory permits you to essentially do record oriented I/O direct to memory. This could be hundreds of times faster than regular file I/O in some situations, particularly in a Windows network.
For example, consider an index file with the following layout:
MAP1 IDXCTL ! control rec
MAP2 INUSE,F ! # recs in idx file
MAP2 JUNK,8
MAP1 IDXREC ! index rec
MAP2 KEY,S,8 ! symbolic key
MAP2 RECNO,F,6 ! rec #
MAP1 RECSIZ,F,6,14 ! size of record
If you were about to execute a process that was going to read every record of the index but didn't update, you could load the entire index file into user memory and then access it directly. (As an added bonus, loading the file into memory will work even if other processes have records locked in the file. If it was important to you to prevent that, then you could always open the file exclusively yourself and then load it into memory.)
Consider the following example:
! load index file (FSPEC) into user memory
XCALL MIAMEX,MX'USRLOD,SLOT,FSPEC
IF SLOT<=0 ? "UNABLE TO LOAD": GOTO ...
...
IDXRECNO = 0 ! read ctl rec (filebase 0)
XCALL MIAMEX,MX'USRIO,STATUS,SLOT,2,IDXCTL
IF STATUS < RECSIZ ? "Error reading...": GOTO ...
...
READ'NEXT'REC:
IDXRECNO = IDXRECNO + 1
IF IDXRECNO > INUSE GOTO DONE
XCALL MIAMEX,MX'USRIO,STATUS,SLOT,2,IDXREC,IDXRECNO
IF STATUS < RECSIZ ? "Error reading...": GOTO ...
...
...
GOTO READ'NEXT'REC
DONE:
! delete file from memory to recover space
XCALL MIAMEX,MX'USRDEL,SLOT,FSPEC
IF SLOT <=0 ? "Unable to delete ";FSPEC
804.0.5. Two new tracing options have been added:
TRACE=USRMEM will trace (to ashell.log) detailed information about the loading and unloading of modules in user memory. It will also indicate when a special work area allocation is being made for a subroutine call.
TRACE=MALLOC will trace (again, to ashell.log) slightly lower level information about all memory allocation and de-allocation operations. In order to get a sense of what the allocations are for, it will help to use this in conjunction with TRACE=USRMEM, but even then, the purpose of some allocations will may remain mysterious.
804.0.6. Reinstate support for A-Shell/FAX. (Feature was inadvertently broken when COM support added.)
804.0.7. The MIAMEX demo/test program has been upgraded to include support for the new USRMEM and MALLOC trace options and the new MIAMEX functions.
804.0.8. SYSTAT.LIT 1.2(130) has been upgraded to support the TRACE options LOCKS, DEBUG, BASERR, ISAM, USRMEM, and MALLOC.
