Added January 2019
ALTRUNEXT=<ext>
ALTSBXEXT=<ext>
The keys ALTRUNEXT and ALTSBXEXT define, respectively, alternate RUN and SBX extensions.
Each of the above keys takes a single 1-3 character extension, which is automatically added to the internal COMPRGEXT list, as well as to the relevant search path, where it will be found BEFORE the corresponding standard extension in each directory of the search path.
The intended usage is to define extensions for test or 'beta' modules that can be easily deployed and removed without overwriting the stable RUN and/or SBX modules. For example, assume we have the following in miame.ini:
ALTRUNEXT=RNX
ALTSBXEXT=SXX
After deploying a release of your package (mixture of RUN and SBX modules), you might later need to fix or enhance a particular program. To avoid affecting the stable version while working on it, you can add the pragma ++PRAGMA FORCE_EXT "RNX" (or "SXX" for a subroutine) to the source so that the compiled version will have the specified alternate extension. When the alternate version is placed into the same directory where the production version resides, the ALTxxxEXT definition will cause it to be loaded in preference to the standard production version, allowing you to easily test the new version. If you decide there's a problem, just erase the new version, which will cause A-Shell to resume using the standard version. Otherwise, you can rename the test version to replace the production version.
Notes
| • | For each directory in the program search path (e.g. [p,pn], [p,0], BAS: ), it will check first for the alternate extension, and only if not found will it check for the standard extension. If neither is found, then the search continues with the next directory in the search path. |
| • | The alternate extension search logic only applies when then extension is not explicit in the command, e.g. would not apply to RUN FOO.RUN or RUN FOO.RNX or VXCALL "FOO.SXX". |
| • | Defining an alternate extension does incur some overhead due to the need for additional directory lookups, so is not recommended unless you actually intend to use the feature. The overhead, however, is likely to be fairly insignificant, except perhaps in cases where you have very large directories. |
| • | For subroutines, the alternate extension will be cached just like the standard extension, and subject to the same automatic refresh logic which insures that the version in memory gets updated or removed when the corresponding version on disk does. The one difference between the behavior of a subroutine with the alternate extension and one with the standard SBX extension is that the alternate version cannot be manually loaded from a non-standard directory (e.g. LOAD MYDEV:FOO.SXX). The problem here is that the automatic refresh logic, after not finding the corresponding module on disk in the search path, will conclude that it has been deleted and thus will remove it from memory and revert to using the standard version. |
| • | If in doubt about which RUN module version was actually loaded, you can activate the FOPENS trace (e.g. SET TRACE FOPENS ON), which will trace the load operations in the ashlog.log file. For example you will see something like this: |
OpenFile1: C:\VM\MIAME\DSK0\150277\FOO.RUN, fh=-1, err=2 [214 us], ...
OpenFile1: c:\vm\miame\DSK0\150000\foo.run, fh=-1, err=2 [355 us], ...
OpenFile1: c:\vm\miame\DSK0\007006\foo.rnx, fh=716, err=0 [371 us], ...
The above indicates that it first tried foo.rnx and .run in [150,277]; the RNX lookup might not be traced if the file isn't present. The another unsuccessful attempt in [150,0], and finally it finds foo.rnx in DSK0:[7,6].
| • | For subroutines, use the subroutine trace (SET TRACE XCALL ON) for a similar trace, e.g. the following traces a subroutine TSTSBX statement, first checking for both the alternate and standard extensions in [150,277], before finding the alternate extension in [150,0]... |
<FOO:25> xcall TSTSBX,S7[BONJOUR]
<FOO:TSTSBX:25> OpenFile1: c:\vm\miame\DSK0\150277\tstsbx.sbx, fh=-1, err=2 [264 us],...
<FOO:TSTSBX:25> OpenFile1: c:\vm\miame\DSK0\150000\tstsbx.sxx, fh=872, err=0 [86 us],...
<FOO:TSTSBX:25> Executing c:\vm\miame\DSK0\150000\TSTSBX.SXX ...
| • | For subroutines, you can also use the MAP statement after running the program to see the names and extensions of the cached routines, although that won't indicate the locations from where they were loaded. |
History
2019 January, A-Shell 6.5.1654: Function added to A-Shell
