A-Shell 6.4 Release Notes

A-Shell 6.4 Release Notes

A-Shell Documentation Series
Copyright © 2017 Jack McGregor. All rights reserved.

This edition was produced on 12 April 2017.


Introduction

This document is a record of the changes made to A-Shell 6.3/6.4, beginning with build 1500 of Autumn 2015. In March 2017, at build 1546.1.2, three things happened:

• The version was renamed from 6.3 to 6.4.

• Active development ceased. From that point forward, only bug fixes and minor enhancements were added to A-Shell. All new development took place in the then-current developers' version, 6.5.

• A new section of this document, "Version Highlights," was created from the existing materials. This became the core of the 6.4 Release Notes.

Changes to the previous versions of A-Shell can be found with their respective software releases on the A-Shell downloads page.

Organization

In addition to the material presented in the Version Highlights sections, this documentation contains two inter-dependent sets of notes:

• Notes by Subject: A record of all new features and improvements that might be of interest to developers. This section does not include bug fixes.

• Notes by Version and Date: A record all A-Shell changes regardless of type or significance, including bug fixes and minor refinements.

Navigation

Any time a topic in the table of contents (at left) displays a little book or folder next to it, click on the topic or mark to expand the table of contents and see the individual notes.

Text Colors

In the "Notes by version and date" section, the authors use text colors to keep track of the status of the different development notes:

• Items that have been transferred to the main A-Shell documentation set (blue)—i.e., the main A-Shell documentation set has been updated with these changes. color = 0,0,204

• Bug fixes, which are not transferred (teal). color = 0,128,128 = teal

• Minor enhancements and changes that do not need to be transferred (violet). color = 153,0,204

• Items which need to be transferred to the main A-Shell docs, but which have not yet gotten there (black).


Version Highlights

New language features:

• MLIST: multi-level list, suitable for storing tree data like XML and JSON

• ORDMAPM: ordered multimap

• Indirect/callback functions

• Passing collections by reference

• B6/I6 variables

New compiler features

• Private functions

• Removal of unused functions from RUN

• LSX improvements

• New pragmas

Internet-related library/protocol updates (HTTP, HTTPS,FTP, AES, TLS, SSH)

HTTP, FTP, CRYPTO clients now supported in Linux

Memory requirements reduced and made more auto-adjustable

New and improved runtime hooks:

• Expanded file hook interface

• Session exit hook

• ATE custom login and splash hooks

Dynamic library XCALL interface: allows XCALL into native libraries, including LIBXL

Web Cache: load/run programs directly from a URL

Numerous new or enhanced subroutines, LITs and SOSLIB functions

Secondary system directory paths: combine standard release with customized directories without overwrite

XTREE enhancements

• Header checkbox

• Indexed PopupMenus

• Sub-Menus

• Footer

ATE enhancements:

• Custom splash/login

• Bidirectional file xfer via internal channel,

• Web launch


Potential Problems

As far as the developers know, there are no problems that you will encounter when updating to A-Shell 6.4, assuming that your starting point is A-Shell 5.0 or later. If you are updating from a 4.x version of A-Shell, please contact MicroSabio to make sure you have the relevant documentation.

Compatibility

A-Shell 6.4 is fully compatible with A-Shell 6.0, which in turn was highly compatible with version 5. No file or program conversions or other modifications are required for the update. All BASIC source code and compiled RUN code is upward compatible, as are all command line switches and CMD/DO files. Of course, if you have a critical production environment, you should probably set up a parallel test run just to make absolutely sure; see Parallel Testing below.

One area of potential concern would be in complex GUI operations, particularly XTREE, where the interface complexity of the control and the vast number of enhancements to it increase the possibility of a subtle differences. But as of the 6.4 release date, there are no known compatibility problems upgrading from 5.0 to 6.0, or from 6.0 to 6.2 or 6.4—or directly from 5.x to 6.4 and skipping any intermediate versions.

Note that updating over the top of an existing version will preserve all existing INI and most other configuration files. Any files that are replaced will be backed up in a subdirectory called BACKUP, in case you need to retrieve or compare them.

If updating from a 4.x version of A-Shell, please consult the release notes for compatibility details. In particular, search for "decimal PPNs", which were introduced in A-Shell 5.0, causing certain known issues with certain known subroutines that manipulate PPNs using 1 byte binary variables.

Recompilation is not necessary but is recommended, as improvements to the compiler may pick up errors that were missed earlier.

Programs that worked under 6.0 may be compiled under 6.4 and will still run under 6.0. Programs using language runtime features introduced in 6.4 will obviously be not backwards compatible. They may launch, but will abort with illegal instruction errors when they encounter a feature that didn’t previously exist.

The qflock.sys and jobtbl.sys files remain compatible from 5.0 thru 6.4. In fact, different versions can run simultaneously, sharing the jobtbl and queue.

Parallel Testing

The best and safest parallel test is one that is totally separate from the production system. Just make a copy of your entire A-Shell directory tree (e.g., /vm to /vm62), install A-Shell 6.4 into the new directory tree, and run some parallel tests. Another approach would be to install A-Shell 6.4 into a new directory tree, but point the data devices and QUEUE in the MIAME.INI to the original devices and QUEUE, so that your earlier copies of A-Shell are accessing the same data and job table. Note that the one DEVICE location which you may not want to share is DSK0:[1,4], since although earlier versions of LITs are compatible with 6.4, the reverse may not be fully true for some LITs.

For example, assume these excerpts from the MIAME.INI in your original, production copy of A-Shell:

DEVICE=DSK0 c:\vm\miame\dsk0\

DEVICE=DSK1 c:\vm\miame\dsk1\

...

QUEUE=100,DISK:c:\vm\miame\qflock.sys

In the new copy, which we'll say you installed in c:\vm62, you would use the following:

DEVICE=DSK0:[1,4] c:\vm62\miame\dsk0\001004\ ; separate new DSK0:[1,4]

DEVICE=DSK0 c:\vm\miame\dsk0\ ; share rest of DSK0:

DEVICE=DSK1 c:\vm\miame\dsk1\ ; and DSK1:

...

QUEUE=100,DISK:c:\vm\miame\qflock.sys ; and the QFLOCK (and JOBTBL)

Once you've completed your tests, you can complete the upgrade by performing a normal update installation of 6.4 over the top of the existing old A-Shell directory tree.


A-Shell BASIC

make sure anything entered below also gets into Compiler Edit History section of LIT….COMPIL.

1546.9.1 | Compiler refinement (edit 797): maximum nesting levels for ++INCLUDE and ++IF conditions increased from 20 to 40. Improve messaging/recovery for the overflow condition.
1538.0.1 | New dot variables .LINENO and .LOCATION.
1534.2.1 | Compiler edit 790: use of .ARGCNT within a PRIVATE_BEGIN / PRIVATE_END block now generates a compile error. Although the expression wouldn't technically be illegal, because the PRIVATE block is essentially called for initialization by whatever function or procedure in the module gets called first, there's really no good way to predict in advance what the .ARGCNT value will represent, and thus it is almost certain to create a discrepancy between the expected and actual behavior.
1534.0.1 | New DIR Switch MEMREG displays the memory required for static variable storage.
1532.1.4 | COMPIL.LIT / COMPLP.LIT 1.1(133) update: /IGOO switch now recognized. This was actually implemented in the internal compiler 779 update when the INCLUDE_GLOBAL_ONCE_ONLY pragma was added.
1530.0.2 | Implemented two New INSTR Flags.
1529.0.1 | Implement major new feature WEBCACHEfor auto-loading required files from web.
1528.0.1 | Language enhancement (compiler edit 776) adds Indirect Function Calls.
1528.0.2 | Compiler enhancement (compiler edit 777) adds New PRAGMAs.
1528.0.3 | Compiler enhancement (compiler edit 778) adds auto-defined macros ABC_CURRENT_ROUTINE$ and ABC_CURRENT_MODULE$. These equate to the current function/procedure name (or "" if none), and the current module filename (file.ext). Both may be useful in standardized error reporting.
1528.0.4 | Compiler enhancement (compiler edit 779) adds pragma ++pragma INCLUDE_GLOBAL_ONCE_ONLY <boolean> . When enabled, ++include is treated as ++include'once, except when it occurs inside a function or procedure. In such cases, it is likely that you are intentionally including an extra copy of some map statements.
1526.0.4 | Language enhancement (compiler edit 773): New IFELSE Functions.
1526.0.1 | New Special File Name .NULL may be used with sequential files to open a file which is not connected to anything.
1523.0.1 | Language/compiler (edit 770) enhancement adds Private Attribute for Functions and Procedures.
1522 | Language enhancement adds bidirectional linked list MLIST.
1521 | Language enhancement: new collection type and Ordered Multi-Map ORDMAPM supports multiple keys of the same value.
1520 | Language enhancement: Passing Ordered Maps may now be accomplished by reference to functions and procedures.
1517.0.1 | Compiler (edit 764) enhancement to recognize the new random generator functions SRAND2 and RND2.
1516.0.1 | Runtime enhancement: Add support for B6 and I6 Variables.


Subroutines

1546.7.2 | REGEX refinement: remove 1024 byte limit on maximum subject string length.
1543.0 | Major MSBBOX Enhancements.
1542.0.10 | DYNLIB.SBR enhancement: automatic conversion from ANSI to/from UTF8 now supported via the "A" (read only) and "a" (read/write) codes. This is used in the Linux version of the LIBXL API to handle accented and other special Latin1 characters.
1542.0.3 | Add new subroutine XSHLEX.SBX.
1540.0.1 | Implement new Group Licensing feature.
1539.0.5 | CRYPTO.SBR Enhancements: Several major improvements including the addition of Linux support.
1538.0.2 | New Fields in FILEHOOK.
1538.0.4 | New MIAMEX function MX_CALLSTACK returns information about the call stack.
1536.0.3 | ATHTTP.SBX 1.2(105) adds support for the HTTP properties parameter (see above), and also for the certpw parameter.
1536.0.2 | HTTP.SBX Enhancement.
1529.0.3 | Add subroutine MX_WEBCACHE.
1526.0.3 | MIAMEX functions MX_GETTRACE and MX_SETTRACE updated to support the TR_JOBLCK (&h000100000000) TRACE flag. Note that this bit is beyond the 32 bit range of the typical 32 bit flags word, so you need to use B5, B6, I6, or F6/F8 to retrieve or set this bit.
1526.0.2 | New subroutine MX_FILESOCK binds a TCP socket to a sequential file channel so that PRINT #CH and/or INPUT #CH transfers data over the socket rather than to/from the file.
1518.0.2 | MX_GETTIME Parameter UTCOFFSET can be used to retrieve the offset between UTC and local time.
1516.0.3 | MX_OCVT now supports 48 bit values, up from 32. This is equivalent to 12 hex characters or 16 octal characters. Note that the standard SOSLIB Fn'Dec2Hex$() function has been updated accordingly.
1515.0.2 | LOG.SBR refinement: status now returns numeric error codes on failure rather than just -1.
1514.0.1 | New subroutine ATELGI allow creation of a customzied ATE login.
1512.1.1 | Source code reorganization: symbols related to AUI_IMAGE have now been separated out of ashell.def into image.def and augmented. Programs using them should now ++include ashinc:ashell.def and ++include:image.def.
1512.1.2 | IMGOP_ACQUIRE now supports optional ability to set the pagesize.
1512.0 | AUI_IMAGE enhancement: IMGOP_INFO now returns the percent black for B&W TIF images.
1510.0.1 | Enhancement to AUI_IMAGE allows the setting of pixel type and resolution.
1510.0.2 | AUI_IMAGE scanning enhancement: the IMGSF_HIDEUI (1) option in the scanflags parameter now works in single-page scanning mode. Previously single page scans (pages=1) always displayed the scanner's user interface regardless of the scanflags.
1510.0.3 | New SOSLIB routine ATEGFK.SBX retrieves a file from the PC via the ATE terminal connection.
1509.0.2 | New MIAMEX function MX_LASTPRTFIL returns the file spec of the last file written by the PDFX printer driver.
1503.0.1 | Add new routine MX_MALLOCLIMIT to get/set MALLOCLIMIT.
1502.0.2 | MX_SYNC refinements: Time elapsed in the sync() or fsync() call is now logged (in microsecond units) if the XDEBUG trace flag set. (This was motivated by suspicions that the sync() call is taking longer under CentOS/RHEL 6 and 7 than under CentOS/RHEL 5. Such suspicions can now be easily quantified.) Also, fsyncing now supported for ISAMA files (e.g. XCALL MIAMEX, MX_SYNC, CH {,STS}).
1501.0.1 | New SIZE.SBR Parameter FLAGS.
1500.0.1 | New XCALL DYNLIB provides general purpose ability to load and call routines in external DLLs (Windows) or shareable libraries (Linux). Initially reserved for internal use in conjunction with the new LibXL library (see next). To be documented later.


LIT Commands

1546.5.2 | SYSTAT.LIT 3.2(178) refinement (UNIX): Reduce the excessive ITC error messages (one per job) to just one overall when the /W mode is unable to send ITC messages due to privilege issues. Allow clean exit with Q or ESC from paging mode.
1542.0.12 | SORT.LIT 1.1(106) now supports localization; see LITMSG.xxx 056,### for message customization. Also, the display has been updated to show the number of records sorted.
1542.0.11 | KILL.LIT 2.2B(125) now supports localization; see LITMSG.xxx 039,### for message customization.
1542.0.4 | SHLEXC.LIT 1.0(103) enhanced (using XSHLEX.SBX, which see above) so that it now works in server environments with ATE or ZTERM clients, auto-transferring the file to the client if necessary. Requires XSHLEX.SBX and ATEAPX.SBX in BAS:
1540.0.2 | SYSTAT.LIT 3.2(175) will display the group each job is assigned to, if applicable, with the /CU switch.
1534.2.4 | HOST.LIT 2.0(106): : reduce minimum partition memory requirement from about 265K to 3K and increase the maximum output capture buffer size (when using /O) from 256K to 512K. Note that the total memory requirement when using /O has actually increased rather than decreased, but it is only required when using /O and in that case it is dynamically allocated outside the memory partition.
1534.2.3 | QUTL.LIT 3.1(129): remove previous maximum of 20000 FLOCK or XLOCK records and reduce the fixed partition memory requirement from approximately 700K to 200K by using dynamic arrays.
1534.2.2 | New DIR Switch MEMREG displays the memory required for static variable storage.
1531.0.2 | New SET.LIT 1.2 Flags DLL, ALL, and ATE.
1531.0.5 | ZTXFER.LIT 1.4(108) now supports /ATE switch to force alternative transfer protocol—i.e. using ATE terminal channel. This was already automatic for transfers between an ATE client and a Windows server, but now can be forced in other situations. For example, under UNIX, FTP/SFTP transfers may be blocked by some security or other obstacle, while the ATE terminal channel would work.
1529.0.4 | Add new LIT file WEBRUN.LIT
1529.0.2 | Add support to SET.LIT for WEBCACHE.
1526.0.2 | SET.LIT 1.2(156) updated to support TRACE flags JOBLCK and EXEC, which were added in 6.3.1518.0.
1515.0.3 | LOG.LIT 3.0(124) now explicitly reports failure to log to directory.
1511.0.1 | VUE 3.2(370) now uses the above technique to disable AutoMouse on the ATE client during the VUE session, then restores the prior settings on exit. Previously, this only occurred for A-Shell/Windows local mode. Note that if the ATE version is prior to 6.3.1511.0, AutoMouse will get disabled on entry into VUE, but not restored on exit.
1506.1.1 | LICENS: Support new 6.3 PIC code format (XXXXXXX-XXXXXX-XXXXXX-XXXXXXX). The new PIC format is needed for certain extensions added in 6.3; it provides no benefits to 6.2 but is hereby supported just as a backwards capability convenience.


Extended Tab Commands

1540.0.4 | AG_WALLPAPER now supports PNG and other image formats for main window wallpaper. This was always the case for dialog wallpaper (see 6.3.1527 below), but previously, main window wallpaper was limited to BMP files.
1531.0.3 | New AG_WEBCACHE command gets/sets webcache options from host.
1527.0.1 | AG_WALLPAPER enhancement: New AG_WALLPAPER Parameter DLGID parameter allows wallpaper to be applied to dialogs.
1511.0.1 | Enhancement to AG_MOUSE restores previous settings.


INFLD

1540.0.3

INFLD enhancement: TYPE code |& ('smart' re-enabling of protected fields), when specified in the INFDEF string, now affects BASIC INPUT fields. (Normally, the INFDEF options only apply to XCALL INPUT, XCALL INFLD, etc.) This can be handy in an application that uses protected fields along with BASIC INPUT, assuming that the BASIC INPUT does not deactivate the protection (which INFLD would otherwise do).


AUI

1542.0.1

AUI_CONTROL enhancement: Auto-Countdown Buttons.


XTREE

1542.0.8

Add XTREE Indexed PopupMenus.

1542.0.7

Add XTREE PopupMenu Sub-Menus.

1542.0.6

XTREE PopupMenu enhancement: individual menu items may now be marked as disabled with a "!" at the start of the item text, i.e.: PopupMenu=!disabled item,VK_xF999; ...

1537

Add new XTREE Footer function.

1530.0.3

New release of the DLL underlying XTREE (SftTree_IX86_U_75.DLL, previously SftTree_IX86_U_70.DLL)

1530.0.4

XTREE enhancement: 3-state editable checkbox columns now support the extended mode (T3+) which adds the ability to check-all (^A), uncheck-all (^B) and undo (^Z).

1530.0.5

XTREE enhancement: extended checkbox columns may now be extended to a second degree by adding a second "+" (e.g. T++ or T3++). This adds a 3-state checkbox to the header of the column which is automatically set to the checked state if all the boxes in the column are checked; the unchecked state if all the boxes are unchecked, or the indeterminate state if there is a mixture (or if all of the boxes are indeterminate). Clicking the checkbox in the header cycles through the check-all, uncheck-all, set-all-to-indeterminate (if 3-state), and back to the origional mixed state (if applicable).

1530.0.6

XTREE enhancement: column ordering for all the columns (up to the max of 100) can now be saved when using the TreeID mechanism with the XTUCFG_COLORD bit set in the XTR'USRCFG field. Previously the limit was 31 columns, which remains the limit when using the XTR'COLORDER() array method without the TreeID option.

1513.0

New XTREE Advanced Coldef Option: MaskView=<mask> . This is identical to the existing Mask=<mask> option, except that the non-numeric mask characters (relative to the current LDF) are stripped from the editable fields returned in the answer array. This is most convenient when you plan to use the data returned from the tree in numeric calculations, where the mask formatting characters may interfere with the conversion from string to number.

1501.5.1

XTREE refinement: Specifying the -$PRINT PopupMenu option was removing the print option from the popup menu, but it was not disabling the ability to print/preview using the built-in ^P command. To disable that, a new Advanced Coldef Option has been added:

Print=Disabled

Note that it doesn't really matter what follows the = sign; the only option is to disable since the default is for printing to be enabled.


ATE

1535.0.1

Add option to Force Calling of ATE Login Dialog Box.

1530.1.2

ATE refinements related to use of the ashell-ate: URL scheme to launch ATE from a web page. These include:

• The MIAME environment variable is now always set to match the location of the miame.ini file. (This is virtually always the case anyway, except that when launched from a URL link, visibility restrictions on the environment between Windows and the browser were resulting in it reverting to C:\VM\MIAME.)

• The Cache and PermCache directories now default to %MIAME%\Cache and %MIAME%\PermCache, respectively, if not set. (This was a potential issue when building a minimal configuration on the fly from the URL.)

• When building the ATE configuration on the fly, you can define pseudo configuration values LoginSBX=<xcallname> and WebRepo=<url dir> to cause ATE to check the web repository for the custom login dialog.

1527.0.4

ATE Enhancement: the -atecfg command line switch used to pass the configuration name to ATE now supports a compound argument up to 1024 bytes long which can be used with the ashell-ate custom URL scheme to pass an ad-hoc configuration as a set of value=attrib pairs. Details of this feature will be documented later.

1519.0.1

ATE enhancement: Allow ATE Custom Splash Display.

1514.0.1

New subroutine ATELGI allow creation of a customzied ATE login.

1510.0.3

New SOSLIB routine ATEGFK.SBX retrieves a file from the PC via the ATE terminal connection.

1502.0.1

ATE and A-Shell/Windows enhancement: the scrollback buffer has been enlarged from 100 to 200 lines.


PDFX

1509.0.1

PDFX enhancement: Passing the WAIT switch to XCALL SPOOL when generating a PDF file using PDFX5+ now results in the routine waiting until the file is written to disk before returning.


Other Topics

1530.0.1 | Run-time enhancement: quoted native filespecs now supported with RUN, e.g. .RUN "/vm/miame/webcache/hello.run"
1526.0.1 | Add MIAME.INI Trace Option JOBLCK.
1518.0.1 | New TRACE option EXEC traces RUN, CHAIN, command line and XCALL AMOS statements.
1507.0.3 | New command line switch: -noclx. When specified as the FIRST argument, it disables the search for the .clx and .cl files.
1507.0.2 | New Command Line File Option CLX.
1507.0.1 | New Command Line Switch MNTSYS.
1502.0.1 | ATE and A-Shell/Windows enhancement: the scrollback buffer has been enlarged from 100 to 200 lines.
1501.3 | Print filter refinement: filter SBX names can now be up to ten characters; previously was six.
1501.2.2 | ATE server-side refinement: increase the wait time on the initial handshake from 3 to 6 seconds. Some large systems with slow/congested/remote networks were occasionally hitting the timeout, causing the session to not recognize that the terminal was ATE.
1500.0.2 | Add support for third-party LibXL library. This library provides the mechanism to read and write XLS files directly, including low level features such as fonts, formats, colors, images, formulas, scroll-lock, individual row/col/cell attributes, etc. Functionality to be exposed to application developers via various API means in subsequent updates.


1547 — 28 March 2017

1547.6.2

Refine

Text mode screen picture refinement: add the pid to the screen picture header. This typically makes it much easier to use the screen pictures for debugging since the pid can be easily matched up to other traces from the same session in the ashlog.log file.

1547.6.1

Fix

Icon DLL loading bug fix: ATE was failing to check for the DLL in the %ATEPERMCACHE% directory prior to reporting the DLL not found error message. Related to the bug fixes, the following refinements to the DLL loading logic have been added:

• A-Shell/Windows now checks both the %ATEPERMCACHE% and %MIAME%\Permcache directories (if not the same) for any DLL not found in the normal search path.

• Failing the above,the alternate search path is CSIDL_PROGRAM_FILES\A-Shell\ e.g. c:\Program Files (x86)\A-Shell. Previously it used the CSIDL_PROGRAM_FILES_COMMON directory but this has been deprecated for the last few Windows versions.

1547.5.3

Refine

Minor internal adjustments for AIX compatibility related to B6 and I6 variables. This is the first AIX release to support them.

1547.5.2

Fix

MX_FILESTATS bug fix: when used to retrieve the stats of a PC file via ATE from an AIX server, the returned file size was garbage.

1547.5.1

Fix

FILL$(pattern,length) bug fix: when length < 0, there was a window of opportunity for the stack to become corrupted, resulting in a variety of undesirable symptoms, including crashing A-Shell.

1547.4.2

Refine

Compiler LSX refinement (edit 803): the line marking the end of a ++include now also indicates the module that we are returning to.

1547.4.1

Fix

Minor correction to the license options display.

1547.3.3

Fix

ATE / MX_AUTOPARENT bug fix: According to the documentation, the auto parent setting should be automatically reset at the start of each program. This was happening, but in some cases it was failing to also inform ATE of the cleared setting.

1547.3.2

Fix

Compiler bug fix (edit 802): The ++IFNLBL conditional, when used with a function or procedure name, in conjunction with the /PX switch, was generating an undefined function error if the function there was a forward reference to a function within a ++IFNLBL conditional block.

1547.3.1

Fix

Compiler LSX bug fixes and refinements (edit 801) :

• The LSX header was failing to note the /px and /igoo switches

• When using /PX, the LSX was something ending up with a superfluous copy of some of the functions shaken out by the /PX logic

• When compiling an LSX file, private variables with the same names that occurred in modules which also had the same names but were in different directories was resulting in bogus duplicate variable name errors.

• Comment lines have been removed from the LSX files to reduce size.

1547.2.1

Fix

APEX: when stretching an image across the entire page, APEX was allowing the equivalent of a double right and bottom margin, causing the preview image to be slightly smaller than it would print. This was mainly noticeable with forms. (The problem was introduced way back in 1511.)

1547.1.1

Fix

Compiler bug fix (edit 800): when using the /LF switch, the resulting LSX file was omitting the last line of ++include files if that last line had no LF terminator.

1547.0.2

Fix

Compiler fix/refinement (edit 799), minor cleanup of LSX contents:

• When using /px, replace the body of functions not called with "{shaken out by /px}"

• Eliminate large blocks of contiguous spaces in function definitions and calls caused by the wrapping of continuation lines onto one line of the LSX listing.

1547.0.1

Fix

Compiler fix/refinement (edit 798): ++INCLUDE'ONCE logic now considers the module's entire path, rather than just the name.ext, when determining whether the module has already been included.


1546 — 16 March 2017

1546.9.1

Refine

Compiler refinement (edit 797): maximum nesting levels for ++INCLUDE and ++IF conditions increased from 20 to 40. Improve messaging/recovery for the overflow condition.

1546.8.1

Fix

Log file refinements. Remove several unconditioned traces from the ashlog.log file, including:

• Certain benign "ISAMX retry" events (now conditioned on ISAM TRACE)

• String stack expansion (now conditioned on MALLOC TRACE)

• Certain XTREE "click thru" messages (now conditioned on XTREE TRACE)

• Message boxes (a configuration mechanism remains to be documented)

1546.7.5

Fix

SYSTAT.LIT 3.2(179) refinement: close a small race condition loophole in the operation of the /K/Z switches in which a new A-Shell session might reclaim the jobtbl record of a phantom or zombie at the same instant that SYSTAT is removing it. This resulted in an immediate "your job has been zapped" error for the newly launched session.

1546.7.4

Fix

ATE server-side fix/refinement: The server will now retry the initial ATE handshake if it times out on the first try. This is intended to reduce the small-but-annoying frequency of degraded connections caused by a very slow network response during the startup. Such connections often appear to work but lead to other handshaking problems later in the session. Retries will now be logged to the ashlog in order to facilitate evaluation of the problem and the degree to which the retry helps.

1546.7.3

Fix

Compiler bug fixes (edit 796):

• Attempt to pass an array by reference to a function is now flagged as an error unless the array is a DIMX DEFSTRUCT. (Previously it was allowed by the compiler but would cause an error at runtime.)

• Fix infinite loop problem compiling a conditional of the form [ ++IF <sym> <relop> <value> ] when the symbol had not yet been defined.

1546.7.2

Refine

REGEX refinement: remove 1024 byte limit on maximum subject string length.

1546.7.1

Fix

ISMUTL.LIT 1.4(142) fixes a bug (introduced in edit 140 or 141) in the Load routine in which it might fail to first get the record size and thus fail to load anything.

1546.6.1

Refine

Minor refinements to install/update package: VC2008 redistributable module removed and is therefore no longer required.

1546.5.2

Refine

SYSTAT.LIT 3.2(178) refinement (UNIX): Reduce the excessive ITC error messages (one per job) to just one overall when the /W mode is unable to send ITC messages due to privilege issues. Allow clean exit with Q or ESC from paging mode.

1546.5.1

Fix

ATE fix to configuration dialog (ATECFX.SBX 4.4.178) converting printer CPP wide values > 100 to "*" (i.e. auto-adjust to page).

1546.2.1

Fix

Log file cleanup: Remove spurious XTREE trace (validate=#, exitpending=#) from the ASHLOG file. It is now correctly conditioned on the XDEBUG TRACE flag.

1546.1.1

Fix

ATE-based SFTP bug fix: Recent updates to the ashnet library which implements SFTP2 "version 2" transfers resulted in a change to the return status on a successful single-file transfer (from 0 to 1), which was causing some file transfer front-ends, like ATSYNC with the /V2 switch and ZTXFER with the /2 switch to report a spurious failure code 1 even when the file was successfully transferred.

1546.1.2

6.3 development cycle now officially at an end; version advanced/renamed to 6.4. At this point there should be only bug fixes to 6.4. All new development will be in version 6.5.

1546.1.1

Fix

XTREE server-side optimization bug fix: under certain conditions, using XTROP_REPLACE to effectively delete rows—by supplying a new array with fewer items than the previous array—was deleting the wrong item due to sorting.


1545 — 06 March 2017

1545.7.1 | Fix | TABX/INFLD bug fix: redisplaying (recreating) an INFLD-based checkbox on a TABX control wasn't displaying the updated state.
1545.6.2 | Add | A new HOSTEX.SBR Suffix character, "^", allows for a slight variation in the Windows behavior.
1545.6.1 | Fix | COMPIL bug fix (edit 794) - the compiler was failing to report an error when a variable type other than F,6 was used as the return variable in a LOOKUP statement. The runtime system, consistent with AMOS behavior, has always returned the value in F,6 format. This fix to the compiler will help prevent unexpected results when another variable type is advertently specified.
1545.5.1 | Fix | XTREE bug fix (server-side): file-mode multi-select trees were failing to return any selections in some cases.
1545.4.3 | Fix | The default Copy/Paste context menu, introduced in 1539.0, is now disabled in the presence of XTREE. The two were conflicting.
1545.4.2 | Fix | TABX/wallpaper bug fix: the main window wallpaper area wasn't being refreshed while a TABX control was present.
1545.4.1 | Fix | TABX bug fix: deleting controls by id or name, which were not part of a TABX control, wasn't working properly when there was a TABX control present.
1545.3.2 | Fix | ERASE.LIT 3.4(130) fixes a display glitch in the /? help display affecting the the /F switch documentation. Also, all the internal messages have now been internationalized via LITMSG.xxx.
1545.3.1 | Fix | MX_FILESTATS bug fix: remote files (on the ATE workstation) with commas in the file name were not being recognized.
1545.2.2 | Fix | Bug fix: further revision to the bitwise operator fix in 6.3.1545.1.
1545.2.1 | Fix | XTREE bug fix: editable cell background color was reverting to white instead of a shade of the display color. Bug introduced in 1545.0
1545.1.1 | Fix | Bug fix: the bitwise operator combinations AND NOT and OR NOT were giving unexpected results when one of the operands was less than &h80000000 and the other was >= &h80000000. Problem was introduced in 6.3.1516 along with support for B6/I6 variables.
1545.0.5 | Fix | libashtls.so.1.1.209.el7 added to the -el7 release. This matches the latest GNUTLS for that platform, 3.3.24, aka ligbnutls.so.28.
1545.0.4 | Fix | EDIT$() bug fix: the +2 flag (to remove control characters) was also removing any characters with the 8th bit set. Bug introduced in 6.3.1534.
1545.0.3 | Add | Add ISMUTL Dump Options.
1545.0.2 | Add | ISMUTL.LIT 1.4(140) adds a new feature to allow dumping directly from the DAT file rather than from one of the indices. This can be useful in the rare case where the IDX file has become damaged, which could interfere with the ability to dump or rebuild it by the normal means.
1545.0.1 | Refine | XY.LIT 1.0(102) adds usage help display, supports XY x,y syntax.

Subtopics

HOSTEX.SBR Suffix

ISMUTL Dump Options


HOSTEX.SBR Suffix

HOSTEX.SBR refinement: a new suffix character, "^", allows for a slight variation in the Windows behavior that you otherwise would get without specifying any suffix character. In both cases, the parent session waits for the child to exit, but in the case of the "^" suffix, it does not try to get the focus back when the child returns, and it doesn't notify any sibling A-Shell sessions when the user transmits keystrokes or mouse events while waiting that are ignored by the child while the parent is waiting.

This addresses an exotic situation with child processes that have no user interface support but which take long enough that it becomes likely for the user to either switch to another session in the meantime, or to try mouse or keyboard actions in the suspended parent session which then interfered with a sibling A-Shell session.


ISMUTL Dump Options

ISMUTL.LIT 1.4(141) adds an option, when dumping directly from the DAT file, to dump just the active records (default), or just the deleted records, or all the records. The latter two options might be useful in exotic data recovery or other operations. For example, if you accidentally deleted some records, you could dump just the deleted records and then reload them, effectively un-deleting them. Or if you have a large file containing many deleted records, you could split it into two files -- one for the active records and one to archive the deleted records -- by dumping the active and deleted records separately and then using them to build two new files from scratch.


1544 — 22 February 2017

1544.9 | Fix | TABX bug fix: when attempting to redundantly add a child control to a TABX panel, the returned control id was incorrect.
1544.8.2 | Fix | File handling bug fix: close loophole in which closing an SQL file within a nested SBX routine might result in the disappearance of the last file opened from the file table, generally leading to I/O to Unopened File error.
1544.8.1 | Fix | TABX bug fix: close a loophole in a recent optimization that was causing an XTREE to fail with error 207 when recreating an already existing tree on a TABX panel.
1544.7 | Fix | LIBASHTLS.DLL 1.1(209): TLS support for TCPX updated to use latest stable GNUTLS (3.4.9). From a library compatibility standard this is known as GNUTLS-30; previously we were using -26. Linux versions to follow.
1544.3 | Fix | Further TABX paint refinement: deleting controls on a TABX panel using the wildcard method (setting text = "*" and specifying a rectangle within which to delete) was failing to visually remove them until some other action triggered a refresh, which may have been too late to prevent visual overwriting/overlapping of newly added controls.
1544.2.2 | Fix | ASHNET.DLL 1.10.158 fixes a variety of minor issues and adds several minor refinements to FTP2, mostly in the area of wildcard and sync operations.
1544.2.1 | Fix | FTP2 bug fix: XFTPF_DEL operation was failing due to bogus complain about library version.
1544.2.1 | Fix | ISAM-A bug fix: GET'PREV following a not-found lookup error on another file was causing the GET'PREV to return the current rather than previous record. The new library version is 6.11q, as shown in ISMUTL. The bug was exposed by the previous ISAM-A patch; see 1542.3.
1544.0.1 | Fix | Various refinements to the TABX display refresh logic to reduce the flickering and other display anomalies.
1544.0.2 | Refine | HTTP.SBR now exposed to Linux via libashnet.so.1.9.157. See notes for CRYPTO under 6.3.1539.0 below for installation details.
1544.0.3 | Refine | FTP2.SBR now exposed to Linux via libashnet.so.1.9.157.
1544.0.4 | Refine | HTTP.SBR refinement: filespecs passed in the request and response parameters are now folded to lower case. The documentation has always noted that they are to be native filespecs, but since case doesn't matter in the Windows world, folding them to lower avoids a common mistake when porting a working application from Windows to Linux.
1544.0.5 | Refine | FTP2 enhancement: wildcards are now supported in the SFTP protocol; previously they were only supported for the FTP protocol.
1544.0.6 | Add | FTP2 enhancements.

Subtopics

FTP2 enhancements


FTP2 enhancements

New opcode options:

Symbol | Value | Description
XFTPF_RECURSE | &h00200000 | recurse subdirs, with wildcards
The following are mutually exclusive (SFTP only); M=missing, N=newer, S=size.
XFTPF_SYNC_ALL | &h00000000 | all matching files
XFTPF_SYNC_M | &h01000000 | all files that don't exist in dest
XFTPF_SYNC_MN | &h02000000 | all files that don't exist in dest, or are newer in source
XFTPF_SYNC_N | &h03000000 | only files that exist in both places but are newer in src
XFTPF_SYNC_MS | &h04000000 | all files that don't exist in dest or are different size
XFTPF_SYNC_MNS | &h05000000 | all files that don't exist in dest or are different size or newer
XFTPF_SYNC_DELM | &h0F000000 | with XFTPF_DEL, only remote files not existing locally

The above opcode options apply only to the SFTP protocol (XTFPF_SFTP), and only come into play when a wildcard is specified in the relevant source argument and the destination is just a directory. The wildcard source argument acts as the first level of filtering on files to be transferred, with further filtering determined by the XFTPF_SYNC_xxx options.

Note that unlike most of the XFTPF_xxx flags, which are coded as unique bits and thus could theoretically be combined in any way, provided it makes functional sense, the XFTPF_SYNC_xxx options are all mutually exclusive—i.e., choose only one. Also note that XFTPF_SYNC_DELM only applies in conjunction with XFTPF_DEL.

When doing wildcard transfers or remote deletions, the status parameter now returns on success the number of files transferred or deleted, rather than just zero. Also, the emsg parameter in that case will contain a list of the files transferred or deleted, delimited by line breaks.

See program FTPTST in SOSLIB:[907,33]


1543 — 03 February 2017

1543.5.2 | Fix | XTREE refinement: missing semicolon at end of PopupMenu definitions now supplied automatically. (It only a problem when concatenating multiple indexed PopupMenus.)
1543.5.1 | Fix | Fix some anomalies in validating new style licenses.
1543.4.2 | Fix | PCKLST/XTREE bug fix: close a loophole in which an empty first line of the file (in file mode) was causing the data load to terminate without displaying any data. Note that this fix is to the server side. Absent the fix, the workaround is to just make sure that the first line of the file contains at least one space if nothing else.
1543.4.1 | Fix | TABX control update/correction: minor adjustments to the new TABX control implementation. Note that the SftTabs_IX86_A_60.dll is no longer supported due to compatibility issues with the new _65.dll.
1543.3.1 | Fix | XTREE bug fix: checkboxes in property sheets were displaying and acting like read-only numbers rather than checkboxes. Bug introduced in 6.3.1530.0.
1543.2.2 | Fix | AUI_CONTROL bug fix: static panel background colors were not display as opaque in the presence of wallpaper, even when the panel was within a dialog. Wallpaper generally requires transparent backgrounds but only for controls that are directly on the wallpaper and intended to bleed through.
1543.2.1 | Fix | AUI_CONTROL bug fix: static controls with palette colors (e.g. values in range of 0-79 rather than RGB values) were not displaying the right color in many cases.
1543.1.1 | Fix | XTREE bug fix: close loophole allowing an infinite loop when a column title contained a ":" character. Bug introduced in 6.3.1537.0.
1543.0 | Add | Major MSGBOX Enhancements.

Subtopics

MSGBOX Enhancements


MSGBOX Enhancements

MSGBOX.SBR now supports up to five buttons, customizeable button labels or icons, tool tips, time delay, time out, hyperlink field, colors, fonts, etc. New syntax:

xcall MSGBOX, msg, title, btnflag, iconflag {, miscflags, rtncde, {mxflags, timeout, timein, url, iconspec,
btn1, btn2, btn3, btn4, btn5,
tip1, tip2, tip3, tip4, tip5,
fontface, fontscale, fgc, bgc}}

The original arguments msg thru rtncde remain as before. If 6 or fewer arguments are specified, it continues to use the original MSGBOX implementation, based on the standard Windows Message Box for GUI environments, or INMEMO for plain text environments.

Otherwise (i.e. if the mxflags argument is specified), the routine uses a new implementation entirely internal to A-Shell. For GUI environments, the new implementation is similar to an extended version of the standard Message Box; for plain text environments it uses the same INMEMO implementation as before. Note that many of the new features will be ignored in the plain text version (icons, tooltips, fonts, hyperlinks, etc.)

New Parameters

mxflags (num) [in]

flags related to extended options:

Symbol | Value | Description
MBX_RCBTNO | &h10000000 | return 101-105 for buttons 1-5
MBX_FRCTXT | &h20000000 | force plain text version
MBX_TI1 | &h00100000 | time-in delay on button 1
MBX_TI2 | &h00200000 | time-in delay on button 2
MBX_TI3 | &h00400000 | time-in delay on button 3
MBX_TI4 | &h00800000 | time-in delay on button 4
MBX_TI5 | &h01000000 | time-in delay on button 5

timeout (num) [in]

if not zero, sets the timeout (in seconds) on the default button, at which point the button is auto-clicked. Except in the case of icon buttons, the button will show the countdown progress.

timein (num) [in]

used in conjunction with the MBX_TIx flags (see mxflags) to specify a time (in seconds) before which one or more buttons are unable to be clicked (i.e. disabled). This is useful when you want to make sure the message box stays on the screen for at least a certain number of seconds, either so that the user can read the message, or perhaps to prevent the possibility of accidentally clicking a button before understanding the consequences.

url (str) [in]

optionally specified a clickable hyperlink that appears beneath the message text and above the buttons. The visible text may be the same as the target url, or you may use HTML format to display something other than the actual link, e.g.

http://www.microsabio.com

<a href=http://www.microsabio.com>MicroSabio Home Page</a>

<a href="http://www.microsabio.com">MicroSabio Home Page</a>

The third example shows the proper HTML format—i.e., with the url field quoted. Note that to embed quotes within a quoted string in BASIC you have to use double-double quotes (""). The second example, without the extra quotes is supported for convenience.

iconspec (str) [in]

optionally specifies an icon (native Windows filespec or iconname::icondll, e.g. "warning:ashico1") to be used instead of the standard one based on the iconflag value, which will be ignored if iconspec is non-null. If neither an iconflag no an iconspec is specified, the message box will have no icon. Note the standard icons specified via the iconflag parameter do not change size with fontscale, but custom icons (specified via iconspec) do scale.

btn1 - btn5 (s,32) [in]

optional text or icon to display for up to 5 buttons—assuming you want to override the default button text corresponding to the btnflag parameter. Although you can mix text buttons and icon buttons, it probably works (or looks) best if you stick to one or the other. For icons, you can use the native Windows filespec of the .ico file or the iconname::icondll format for an icon within an icon library (like ashico1.dll). Note the 32 byte limit on the length of each field; for ico filespecs, to fit within 32 characters you may need to drop the directory from the path and either put the icon in the current directory or in the default A-Shell icon search path—e.g. the cache, permcache, or icons subdirectories.

tip1 - tip5 (str) [in]

optional tool tips for up to 5 buttons.

fontface (str) [in]

optional font to use

fontscale (num) [in]

optional font scale adjustment in percent. 0 is treated the same as 100 percent. In modern high-res environments, you may find that increasing the font size makes for a more readable message. Note that the font scale does not affect the title bar, but it does affect nearly everything else in the message box. See note under iconspec.

fgc (num) [in]

optional RGB value to use for the message text.

bgc (num) [in]

optional RGB value to use for the background of the message.

Comments

Aside from the features documented above, another advantage of the enhanced message box (vs the standard Windows message box) is that although it forces you to respond to the message box before returning to the application (i.e. it is task modal), it allows you to access the A-Shell menu bar, for example, to use the Print Screen utility.


1542 — 22 January 2017

1542.2 | Fix | Fix XTREE bug (introduced in 6.3.1536.0) in which clicking on a checkbox or radio button in an inactive tree was toggling the visual state of the element, but not returning the updated state in the answer array.
1542.1 | Fix | XTREE bug fix: close loophole in which an empty shared list column might result in truncation of the answer array results.
1542.0.13 | Fix | ISMBLD.LIT/SBX 2.1(143) bug fix: SBX version wasn't putting the IDA on the same device as the IDX when the fspec contained a device specification and the IDADEV parameter was blank.
1542.0.12 | Refine | SORT.LIT 1.1(106) now supports localization; see LITMSG.xxx 056,### for message customization. Also, the display has been updated to show the number of records sorted.
1542.0.11 | Refine | KILL.LIT 2.2B(125) now supports localization; see LITMSG.xxx 039,### for message customization.
1542.0.10 | Refine | DYNLIB.SBR enhancement: automatic conversion from ANSI to/from UTF8 now supported via the "A" (read only) and "a" (read/write) codes. This is used in the Linux version of the LIBXL API to handle accented and other special Latin1 characters.
1542.0.9 | Fix | SIZE.SBR bug fix: The variations to count the number of lines—flags 1 and 2—were incorrectly including the byte count.
1542.0.8 | Add | Add XTREE Indexed PopupMenus.
1542.0.7 | Add | Add XTREE PopupMenu Sub-Menus.
1542.0.6 | Add | XTREE PopupMenu enhancement: individual menu items may now be marked as disabled with a "!" at the start of the item text, i.e.: PopupMenu=!disabled item,VK_xF999; ...
1542.0.5 | Refine | xMASCB.SBR routines fixed to support the dynamic string stack.
1542.0.4 | Refine | SHLEXC.LIT 1.0(103) enhanced (using XSHLEX.SBX, which see above) so that it now works in server environments with ATE or ZTERM clients, auto-transferring the file to the client if necessary. Requires XSHLEX.SBX and ATEAPX.SBX in BAS:
1542.0.3 | Add | Add new subroutine XSHLEX.SBX.
1542.0.2 | Fix | ASHNET.DLL 1.9.157 bug fix: resolve various problems with the plain FTP protocol support in the FTP2.SBX routine. The ASCII/BINARY and PASSIVE/ACTIVE options weren't working, nor was the simple PC-to-host option. Presumably the excuse for this oversight was that hardly anyone uses plain FTP anymore, preferring SFTP instead.
1542.0.1 | Add | AUI_CONTROL enhancement: Auto-Countdown Buttons.

Subtopics

Auto-Countdown Buttons

XSHLEX.SBX

XTREE PopupMenu Sub-Menus

XTREE Indexed PopupMenus


Auto-Countdown Buttons

To enable this feature, append "<##>" to the text of a button (ctype MBF_BUTTON), where ## is the desired length of the countdown in seconds. The button display will be updated each second with the remaining length of the countdown until it reaches zero. At that time, the "<##>" suffix will be removed entirely, and one of the following two events will occur:

• enabled. This might make sense in a situation where you want to prevent the user from prematurely or accidentally triggering an action with serious consequences.consequences.

• If the button was initially enabled, then the click event will be triggered.


XSHLEX.SBX

This subroutine has been added to the standard A-Shell distribution package so as to provide a standardized robust way of doing a "Shell Execute"—i.e. launch the application that goes with a specified file or URL object—without having to consider which platform you are using. This does not provide much advantage over MX_SHELLEX for those in a pure local Windows environment, but for developers programming across various environments, it eliminates the need for logic to deal with local/remote and file transfer considerations. For example, in an ATE environment, it detects if the object is a file on the server, and if so, transfers it automatically to the ATECACHE directory when it then launches the corresponding app.

xcall XSHLEX, objectspec {,status, action, parms, dir, showflags, waitflag, clisvr, exitstatus}

The parameters all correspond to the equally named MX_SHELLEX parameters, which see for specifications. Only the deviations/extensions from the MX_SHELL parameter descriptions are noted below. Also note that the order of the first two parameters is reversed from MX_SHELLEX, reducing the minimum syntax to a single parameter.

objectspec (str) [in]

File or URL to launch. Unlike MX_SHELLEX, the file spec may be in AMOS format; the routine will figure out if it is relative to the server or the client. If on the server in an ATE or ZTERM connection, file will be transferred to the client for launch using ATEAPX.SBX.

status (num) [out]

Combines status codes returned by MX_SHELLEX, with those of ATEAPX.SBX (which is used for file transfer if necessary) and adds a few more. The best reference, both for documentation and actual program usage, is the function Fn'Shell'Exec'Status'Description$() in the new SOSLIB fnshellex.bsi [https://bitbucket.org/microsabio/soslib/src/bb6659e417127151e863126f35cf6213cba5ccce/907010/fnshellex.bsi?at=default&fileviewer=file-view-default] function.

action, parms, dir$, showflag, waitflag, exitstatus

same as for MX_SHELLEX

clisvr (str) [in]

Similar to MX_SHELLEX usage, except that if omitted or blank, the routine will attempt to figure out if objectspec is a file on the server or client. If the application knows the object is on the client PC, it can set it to "C" (for client) to avoid the self-determination logic.

Comments

The new fnshellex.bsi module (see link above) contains a convenient wrapper function Fn'Shell'Exec(objectspec$) for maximum simplicity, e.g.:

STATUS = Fn'Shell'Exec(objectspec$)


XTREE PopupMenu Sub-Menus

An enhancement to the XTREE PopupMenu now supports sub-menus. The syntax is the same as for Hover/Context menus, i.e. set the cmd field (of the text,cmd; menu item pair) to "[SUB]" to mark the beginning of the submenu, and the text field of a subsequent item to "[ENDSUB]" to mark the end of the submenu. For example:

coldef$ += "0~0~ ~SH~PopupMenu=" &

+ "!Retire\tF2,VK_xF501;" &

+ "|arrow_right_green::ashico1|Peacetime,[SUB];" &

+ "|photo_portrait::ashico1|Visit\tF3,VK_xF502;" &

+ "|signpost::ashico1|Pass Through,VK_xF503;" &

+ "[ENDSUB],;" &

+ "-----,;" &

+ "|gear::ashico1|Wartime,[SUB];" &

+ "Attack,VK_xF504;Lay Siege,VK_x507;" &

+ "[ENDSUB],;" &

+ "-----,;" &

...

The codeabove defines a PopupMenu which looks something like this:

Retire F2 (disabled item)

Peacetime (submenu with icon)

Visit F3 (submenu item with icon)

Pass Through (submenu item with icon)

--------------------- (separator)

Wartime (submenu with icon)

Attack (submenu item)

Lay Siege (submenu item)

--------------------- (separator)

...


XTREE Indexed PopupMenus

An enhancement to XTREE provides support for indexed PopupMenus. These allow for column- and/or row- specific context menus to be assembled by concatenating one or shared partial indexed menus. To accomplish these three new variations of the PopupMenu syntax are introduced:

PopupMenu:?=lbl1,cmd1;lbl2,cmd2;...lblN,cmdN

PopupMenu={+}?{???}

PopupMenu={+}###

where each ? is replaced by an alphabetic character A-Z, and ### is replaced by a column number.

The first variation defines a full or partial menu to be indexed by the letter replacing ?. The definition can be attached as an Advance Coldef Option clause to any column definition (zero column or a real column). Unlike the standard PopupMenu definition syntax, the resulting menu is not automatically invoked; it only becomes available for reference via one of the other syntax options associated with a real column.

The second variation may be associated with a real column, indicating that the context menu for that column should be made up of the previously indexed menus associated with the ? character(s). The optional "+" prefix prepends the global PopupMenu to the start of the column-specific menu. For example:

PopupMenu=+AQZ

indicates that the context menu for the column should be made from the global PopupMenu, combined with the indexed PopupMenus A, Q, and Z.

The third variation indicates that the specified column ### (current row) contains the list of indexed PopupMenus to be used for this column, thus allowing the possibility of a different set of context menu items for each cell. Note that the specified column ### would normally be hidden, but it doesn't have to be.

See the EXLIB sample program XTRA21 for an example.


1541 — 21 December 2016

1541

Add

XTEXT enhancement: new flag TXF_SILENT (&h00100000) eliminates the user interface and causes the operation to exit immediately. This is mainly useful in conjunction with TXOP_CREATE to convert a file from one format into another.


1540 — 19 December 2016

1540.0.4 | Refine | AG_WALLPAPER now supports PNG and other image formats for main window wallpaper. This was always the case for dialog wallpaper (see 6.3.1527 below), but previously, main window wallpaper was limited to BMP files.
1540.0.3 | Add | INFLD enhancement: TYPE code |& ('smart' re-enabling of protected fields), when specified in the INFDEF string, now affects BASIC INPUT fields. (Normally, the INFDEF options only apply to XCALL INPUT, XCALL INFLD, etc.) This can be handy in an application that uses protected fields along with BASIC INPUT, assuming that the BASIC INPUT does not deactivate the protection (which INFLD would otherwise do).
1540.0.2 | Add | SYSTAT.LIT 3.2(175) will display the group each job is assigned to, if applicable, with the /CU switch.
1540.0.1 | Add | Implement new Group Licensing feature.

Subtopics

Group Licensing


Group Licensing

Group Licensing allows fine tuning of the license usage by providing a means of reserving and/or limiting the license usage relative to license groups. For example, in a 15 user license, you can reserve 2 license for "admin" users, and limit the "remote" users to no more than 5 licenses.

When group licensing is enabled (in the license code), A-Shell will call BAS:ASLICGRP.SBX on startup (if it exists) to determine which license group the current user should be assigned to, and also to specify the number of licenses that each group should be allocated or limited to.

See the sample ASGRPLIC.SBX source code in [907,52] of the SOSLIB for details on the calling interface.


1539 — 11 December 2016

1539.0.5 | Add | CRYPTO.SBR Enhancements: Several major improvements including the addition of Linux support.
1539.0.4 | Fix | CGIUTL bug fix: HTML decoding of an explicit string request passed to CGIOP_GETPARX or _GETPARARY was failing if the string length was > 2K.
1539.0.3 | Refine | XTREE refinement / enhancement: the Advanced Coldef Option dspwid may now be explicitly set to 0 (Dspwid=0) to produce an effect similar to hiding the column (Cformat "H"), except that the column is still technically visible (just 1 pixel wide). This allows you to manually resize it with the mouse (not possible for truly hidden columns), and also may be useful in exotic situations. For example, you may have a column that you want to leave essentially invisible for rows where it is empty, but let it spill over to subsequent columns for rows where it is not empty.
1539.0.2 | Refine | Window UI refinement: right clicking on a dialog or the main window will now generate a generic copy/paste context menu if there is not a custom context menu already defined.
1539.0.1 | Refine | Windows UI refinement: blocks can now be marked starting from the lower right corner and dragging to the upper left. Previously, only marking down and to the right was supported.

Subtopics

CRYPTO.SBR Enhancements


CRYPTO.SBR Enhancements

Parameters

Add new parameters initialization vector (iv), additional authentication data (aad) and authentication tag (authtag). New syntax is:

XCALL CRYPT, opcode, status, src, decoding, src, encoding, cflags {, cipher, key, keybits, cmode, padding {, cbsrc {, iv {, aad, authtag}}}}

iv (String or Unfmt) [in]

Initialization vector for optional use with CRYPTOP_ENCRYPT/DECRYPT opcodes with the AES cipher (all cipher modes except ECB). For cipher modes other than GCM or ECB, it should match the cipher block size, i.e. 16 bytes for AES (128 bits, not to be confused with the key size). For GCM cipher mode, 96 bits or less is recommended for best efficiency and interoperability. In all cases, it should be unique for any given key, preferably randomly generated. For GCM, it is only necessary that each IV not be used more than once. The same iv used for the encryption must be supplied to the decryption. The iv may be specified as raw bytes (preferably using an X format variable), or as a string of hex digits (in which case the CRYPF_IVHEX flag must be specified.)

aad (String, null terminated) [in]

Additional authentication data for use with the new GCM cipher mode (see below). Must be in the format of a string of hex digits. This is typically used to provide an identifying label or other association for the encrypted text, with the intent of making sure that the decrypted text is not just valid, but valid for a particular context/use. A corresponding authentication tag is generated (by combining the aad with the message and hashing and encrypting it) and output to the authtag parameter. The aad does not have to be kept secret, but both it and the corresponding authtag must be provided to the decryption routine in order to authenticate the result. The aad parameter can be null, but a unique authtag will still be generated and must be passed (along with the null aad) to the decryption.

authtag (String, 33+ bytes) [in/out]

Required for AES-GCM encryption/decryption. During encryption, an authentication tag is generated from the combination of the aad and the message text and output to this parameter in the form of a string of 32 hex digits. This computed value must then be passed along with the origional aad to the decryption.

Cipher Modes

Add new cipher modes (cmode) added for use with the AES encryption algorithm. See CIPHER.DEF table below.

Padding

The following text was added to the parameter description for padding:

Note that the stream cipher modes (CTR,CFB,OFB,GCM) do not require or use padding and thus ignore the padding parameter (use of CRYPT_PAD_NA recommended for clarity). Without padding, the encrypted text is the same size as the plain text (assuming the same encoding). The block cipher modes (ECB and CBC) do require one of the other padding options, all of which will increase the encrypted text size up to a multiple of the block size (i.e. a multiple of 16).

Linux

This release enables CRYPTO.SBR for A-Shell/Linux; previously only A-Shell/Windows was supported.

CIPHER.DEF

New symbols in ashinc:cipher.def

Cipher | Value | Description
CRYPTO_MODE_CTR | 4 | Counter Mode (stream)
CRYPTO_MODE_CFB | 5 | Cipher Feedback (stream)
CRYPTO_MODE_OFB | 6 | Output Feedback (stream)
CRYPTO_MODE_GCM | 7 | Galois/Counter Mode (stream)
CRYPF_IVHEX | &h0800 | IV is hex-encoded, else binary.
CRYPTO_PAD_NA | -1 | Padding not applicable; use with stream cipher modes CTR, CFB, OFG, GCM.

Libraries

All of the CRYPT-related enhancements described above require ASHNET.DLL 1.9.156+ (Windows) or libashnet.so.1.9.156 (Linux).


1538 — 05 December 2016

1538.1 | Fix | XTREE bug fix / refinement: cformat code "o" (to allow previous column to spill over into the current one) was not working in file mode when the column also had a cell background color (cformat "B").
1538.0.4 | Add | New MIAMEX function MX_CALLSTACK returns information about the call stack.
1538.0.3 | Fix | File hook bug fix: the recno field in the ST_HOOK_ENV wasn't being adjusted for non-zero SCALE factors.
1538.0.2 | Add | New Fields in FILEHOOK.
1538.0.1 | Add | New dot variables .LINENO and .LOCATION.

Subtopics

.LINENO and .LOCATION

New Fields in FILEHOOK

MX_CALLSTACK


.LINENO and .LOCATION

Add new dot variables .LINENO and .LOCATION in compiler edit 792:

• (which returns the physical line # since the last page break in the output file open on the specified channel).file open on the specified channel).

• in bytes from the start of the current program (RUN, LIT or SBX) to the current statement position. Note that the location counter is generally represented in hex (as it appears in the LSX files created by the compiler /LF switch), so you would probably want to print it using the SOSLIB function Fn'Dec2Hex(.LOCATION). SOSLIB function Fn'Dec2Hex(.LOCATION).


New Fields in FILEHOOK

Add new fields chan, location and lineno to the ST_HOOK_ENV structure passed to the hook SBX. These are mostly motivated by the desire to use the hook mechanism more for application forensics than for traditional purposes (export, data audit); i.e. they allow the hook return to more information about the context in which the file operation occurred.

The end of the ST_HOOK_ENV structure now looks like this:

map2 user,s,24 ! user name

map2 chan,b,4 ! actual file channel (may not match fileid)

map2 location,b,4 ! location counter

map2 lineno,b,2 ! last line #

Note that the expanded structure does not break compatibility with existing hook routines, nor do hook routines using the expanded structure lose their backwards compatibility. The new fields just won't be available.

See ASHINC:HOOK.DEF for the updated structure and related symbol defintions.


MX_CALLSTACK

New MIAMEX function MX_CALLSTACK (189) returns information about the call stack. The motivation here, as with the enhancement to the ST_HOOK_ENV structure, is to allow application routines to identify the context in which they were called. For example, the file hook subroutine, or an error trapping routine, might want to identify not just the location where the file operation or error occurred, but if that location was within a callable routine, the routine(s) that called it. The syntax:

xcall MIAMEX, MX_CALLSTACK, maxdepth, csarray(1) {, program$}

maxdepth (num) [in/out] should be set to the number of elements in the csarray(), i.e. the maximum number of stack levels (working backwards from the current stack frame context) to retrieve. On return, it will be set to the number of levels in the current stack. (If greater than the number you originally specified, it indicates that not all of the levels were returned.)

csarray(1) (array of ST_CALLSTACK) [out] is the first element of an array of structures defined in ASHINC:CALLSTACK.DEF as follows:

defstruct ST_CALLSTACK

map2 calltype,b,2 ! type of call (see CSTF_xxx)

map2 src'lno,b,2 ! line # at or prior to call

map2 src'loc,b,4 ! location counter at call

map2 dst'loc,b,4 ! target location (for call, fn, proc)

map2 dst'name,s,52 ! name of sbx or AMOS command line

endstruct

Typically csarray() would be defined via:

dimx callstack(MAX_CALLSTACK), ST_CALLSTACK

(MAX_CALLSTACK should be set to the maximum # of levels you want to retrieve.)

program$ (string) [out] optionally returns the main program at the top of the callstack.

Example:

++include ashinc:ashell.def

++include ashinc:callstack.bsi

define MAX_CALLSTACK = 10

map1 misc

map2 program$,s,10

map2 stackdepth,i,2

dimx callstack(MAX_CALLSTACK), ST_CALLSTACK

stackdepth = MAX_CALLSTACK ! max # levels we can handle

xcall MIAMEX, MX_CALLSTACK, stackdepth, callstack(1), program$

for i = 1 to stackdepth min MAX_CALLSTACK

? Fn'Call'Stack'Descr$(callstack(i))

next i

The Fn'Call'Stack'Descr$() function referenced above is in the SOSLIB module ASHINC:CALLSTACK.BSI. It creates a one line description of a call (gosub, procedure, function, xcall, amos statement, etc.) from one location/context to another. An example showing a context six levels deep looks like this:

from loc 3B7 call proc() @3DF

from loc 38C fn'() @393

from loc 32B call proc() @331

from loc 4F1 xcall callstack1

from loc 47C fn'() @483

from loc 323 call proc() @41A

Notes

• weren't listed in the output. weren't listed in the output.

• match up the location counter values to source code lines, see the LSX file created by the compiler /L switch.LSX file created by the compiler /L switch.

• the code that executed the MX_CALLBACK function. So in the above case, the current code is within a procedure that starts at location 3DF (hex) and was called from location 3B7. Location 3B7 is within a function that starts at location 393, which in turn was called from location 38C, etc.location 393, which in turn was called from location 38C, etc.


1537 — 27 November 2016

1537.1 | Fix | XTREE: XTROP_REPLACE was resulting in some editable cell data anomalies after identical changes by the application to both the data and answer arrays.
1537.0 | Add | Add new XTREE Footer function.

Subtopics

XTREE Footer


XTREE Footer

XTREE enhancement: You can now define a footer, which is like a mirror of the header, i.e. a line which remains fixed and is not affected by scrolling or by loading/updating of data or answer lines.

To enable and configure the display of the footer line, two new fields have been added to the bottom of the XTRCTL parameter structure, which now ends like this:

...

map2 XTR'CTLID,B,2 ! A-Shell ctl #

map2 XTR'LEFTINDEX,B,1 ! Left-most visible column

map2 XTR'SHOWFOOTER,B,1 ! Show footer

map2 XTR'FOOTERSTYLE,b,1 ! same XTHSF_xxx flags as HEADERSTYLE (6.3.1537+)

map2 UNUSED2,X,12 ! was 14

! (total size = 128)

To enable the display of the footer, set the SHOWFOOTER field to 1. The FOOTERSTYLE field can be used to adjust the attributes of the footer, using the same options as in the HEADERSTYLE field for the headers.`

To define the display contents of each column in the footer, you can append a clause to the header field of the coldef. The footer clause must begin with a pair of colons (::) followed by a string of text which has follows the same syntax as for the header. For example, the following COLDEF excerpt defines a column starting in position 9, 12 characters wide, with "Qty" in the header and "Total Qty" in the footer...

COLDEF += "9~12~Qty::Total Qty~#EX~~"

In practice, you might want to replace the generic description "Total Qty" with the actual total for that column. To do that, you would need to sum the column in the application (initially, and/or after any changes to the column), and then the COLDEF string would have to be rebuilt with the updated footer definition, e.g.

COLDEF += "9~12~Qty::Total: "+TOT'QTY using "#####"+"#EX~~"

(The COLDEF for an existing tree can be updated by just passing the new COLDEF string in an XTROP_REPLACE or XTROP_RESELECT call.)

You may also define font, scale, and color attributes using the following new Advanced Coldef Options:

FooterFont= (same syntax as for HeaderFont)

FooterScale= (same syntax as for HeaderScale)

RGBbgFooter= (same syntax as for RGBbgTotals)

RGBfgFooter= (same syntax as for RGBfgTotals)


1536 — 17 November 2016

1536.3.3 | Refine | ATHTTP.SBX 1.2(106) removes the 256 byte limit on the length of the returned response string. The new theoretical limit is 500K, although there may be other effective limitations based on resources, timing, etc.
1536.3.2 | Refine | ASHNET.DLL 1.8.154 refinement: the properties options introduced in 1.8.153 now apply to the HTTPF_REQGET ("simple get") operation as well as the other operations/modes; previously they were ignored for the simple get. Also, the default timeout parameters (30 seconds on connection, 75 on read) now apply to the HTTPF_REQGET operation even if properties are not explicitly specified. Previously the timeouts were indeterminate, but definitely shorter than the new defaults.
1536.3.1 | Fix | Fix MBF_VCENTER with static controls (reverted to top-justification in 6.3.1535.0).
1536.2 | Fix | Fix XTREE bug related to use of a date picker control for editing a cell within an XTF_SPLIT tree. If the column had to be enlarged to fit the date picker, the resulting layout was a bit crazy. (Same as 6.2.1428.8)
1536.1 | Refine | XTREE performance optimization: updating the answer array on exit from an editing session is now considerably faster than before. In most cases, this may not be obvious because it was already fast. But there were some cases, in particular large XTF_SPLIT trees with an editable expand/collapse state column (=UH) were the speed up is quite noticeable (from a few seconds down to a few milliseconds).
1536.0.5 | Refine | XTREE performance optimization related to the return of editable cell data from tree to application. Particularly in the case of XTF_SPLIT, the improvement could amount to seconds for very large trees.
1536.0.4 | Fix | Fix bug (introduced in 6.3.1524) which resulted in spurious error #13 (file already open) errors in certain sequences where a file channel is closed and then reopened.
1536.0.3 | Add | ATHTTP.SBX 1.2(105) adds support for the HTTP properties parameter (see above), and also for the certpw parameter.
1536.0.2 | Add | HTTP.SBX Enhancement renames the certfile parameter to properties and expands its usage.
1536.0.1 | Refine | ASHNET.DLL 1.8.153: relink with updated SSL, SFTP and HTTP libraries to incorporate many minor bug fixes and improvements in the underlying libraries over the last 11 months. The DLL is backwards compatible to A-Shell and ATE 6.2.

Subtopics

HTTP.SBX Enhancement


HTTP.SBX Enhancement

In HTTP.SBX, rename the certfile parameter to properties and revise its meaning/interpretation to:

Properties (string) [in]

An optional list of name=value clauses delimited by semicolons, e.g.: name1=value;name2=value2,value3;...;nameN=valueM

To maintain backwards compatibility, if there is no "=" character in the string, it will be intepreted as the certfile spec (as before), although this syntax is now deprecated and replaced with the cert=fspec clause).

The current list of property names and values is shown below. Note that the property names are case sensitive, but the values are not. For boolean values, anything starting with "T" or "1" is considered TRUE; everything else is considered false. Note the default values for the case where the property is not specified.

Name = Value | Default | Description
Cert=<fspec> | none | Specify cert file spec
AllowHeaderFolding | True | Disables MIME header folding
BasicAuth | False | Allows HTTP basic authentication; see Comments.
RequiresSslCertVerify | False | If true, verify server's SSL cert; if expired or invalid, abort connection.
SslAllowedCiphers | <all> | Specify comma-delimited list of allowed SSL/TLS ciphers See Comments.
AutoAddHostHeader | False | If true, the "Host" header will be added to the request header for XHTTPF_REQGET
MimicFireFox | False | If true, headers are added to XHTTPF_REQGET calls to mimic those used by FireFox
MimicIE | False | If true, headers are added XHTTPF_REQGET to mimic those used by Internet Explorer
ReadTimeout | 75 | Time in seconds to wait while reading the response from the server before timing out.
ConnectTimeout | 30 | Time in seconds to wait for the connection to be established before timing out

Table Comments

BasicAuth: Basic Authentication is one of many types of HTTP authentication, but it is often considered a security risk because the name and password are transmitted in plain text. For an SSL/TSL connection, this may be ok, but in any case, the default is set to False just to err on the safe side.

SslAllowedCiphers: To limit SSL/TLS connections to a more specific set of possible ciphers, specify one or more of the following (comma-delimited). You may also use the special value "best-practices" to request "current best practices". Currently this means the following, but may evolve over time:

• Any RSA keys must be 1024 bits or more

• All renegotiations must be secure

• All ciphers using RC4, DES or 3DES are disallowed

Available ciphers

TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 | TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 | TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 | TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 | TLS_DHE_RSA_WITH_AES_256_CBC_SHA
TLS_RSA_WITH_AES_256_CBC_SHA256 | TLS_RSA_WITH_AES_256_GCM_SHA384 | TLS_RSA_WITH_AES_256_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 | TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 | TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 | TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 | TLS_DHE_RSA_WITH_AES_128_CBC_SHA
TLS_RSA_WITH_AES_128_CBC_SHA256 | TLS_RSA_WITH_AES_128_GCM_SHA256 | TLS_RSA_WITH_AES_128_CBC_SHA
TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA | TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA | TLS_RSA_WITH_3DES_EDE_CBC_SHA
TLS_ECDHE_RSA_WITH_RC4_128_SHA | TLS_RSA_WITH_RC4_128_SHA | TLS_RSA_WITH_RC4_128_MD5
TLS_DHE_RSA_WITH_DES_CBC_SHA | TLS_RSA_WITH_DES_CBC_SHA |


1535 — 11 November 2016

1535.3 | Fix | Resolve intermittent crash in CGIUTL opcode 6 (CGIOP_MRGFIL). Same patch as in 6.2.1428.7.
1535.2.3 | Fix | ATE: Remove the text message "remote connection has been terminated by host/user". It had become either superseded by the dialog, or superfluous.
1535.2.2 | Fix | Compiler edit 791: certain obscure syntax errors were putting the compiler into an infinite loop.
1535.2.1 | Fix | Eliminate spurious runtime error when passing .NULL to a function parameter expecting an array passed by reference. Note that the way to test for this within the function is to check if .EXTENT($ARY()) < 0.
1535.1.2 | Fix | Update start.cmd[901,2] and ashupd.lit to reference new Bitbucket repository rather than the outdated SOSLIB update package.
1535.1.1 | Fix | Replace old acorn and ate icons with the newer A-Shell and ATE icons. For various reasons, the old versions were hanging around and resurfacing when they should have been replaced long ago.
1535.0.2 | Fix | AUI_CONTROL static text controls with BGC=NUL_BGC (-2) now inherit the background color of a parent TABX panel even when using MBF2_CUSTDRAW or MBF_VCENTER.
1535.0.1 | Add | Add option to Force Calling of ATE Login Dialog Box.

Subtopics

Force Calling of ATE Login Dialog Box


Force Calling of ATE Login Dialog Box

ATE enhancement: add checkbox option to login panel of configuration dialog (atecfx.sbx 4.4(176)) to force the login dialog to be called prior to the connection attempt. This addresses two situations in particular:

• the case where you want to display your custom login dialog prior to connection even when the login name and password appear to be already set.

• the ATSD case where ATE cannot rely on standard login status information—or the existence of a name and/or password—to determine if the login dialog needs to be displayed.

Previous to 6.3.1516 the login dialog was only called after a login failure. Starting in 6.3.1516, it was called prior to the first connection attempt if either the name or password field was blank. Now it is called for the following conditions:

• the Login Dialog option is checked

• the name and/or password is set to "[INIT]"

• under UNIX, the login credentials passed to the server are rejected.


1534 — 02 November 2016

1534.2.4 | Refine | HOST.LIT 2.0(106): : reduce minimum partition memory requirement from about 265K to 3K and increase the maximum output capture buffer size (when using /O) from 256K to 512K. Note that the total memory requirement when using /O has actually increased rather than decreased, but it is only required when using /O and in that case it is dynamically allocated outside the memory partition.
1534.2.3 | Refine | QUTL.LIT 3.1(129): remove previous maximum of 20000 FLOCK or XLOCK records and reduce the fixed partition memory requirement from approximately 700K to 200K by using dynamic arrays.
1534.2.2 | Add | New DIR Switch MEMREQ displays the memory required for static variable storage.
1534.2.1 | Refine | Compiler edit 790: use of .ARGCNT within a PRIVATE_BEGIN / PRIVATE_END block now generates a compile error. Although the expression wouldn't technically be illegal, because the PRIVATE block is essentially called for initialization by whatever function or procedure in the module gets called first, there's really no good way to predict in advance what the .ARGCNT value will represent, and thus it is almost certain to create a discrepancy between the expected and actual behavior.
1534.1 | Refine | ATE: remove previous limit of 1K on length of string returned by AG_XFUNCS.
1534.0.2 | Fix | XTREE: when using XTROP_CREATE to replace an existing tree, not all attributes of the origional column definitions were being reset. This was resulting in some oddities where a column in the new tree might retain some attributes from the corresponding column in the old tree.
1534.0.1 | Add | EDIT$ Enhancements to deal with quotes.

Subtopics

DIR Switch MEMREQ

EDIT$ Enhancements


DIR Switch MEMREQ

DIR.LIT 3.3(160) enhancement: new /MEMREQ switch displays the memory required for static variable storage for programs such as LIT, RUN and SBX files in place of the file size. When both /SSIZE (sort on file size) and /MEMREQ are specified, it also sorts based on the memory requirement.

Note that the value displayed by /MEMREQ is only a total for the combined sizes of the fixed variables in the program. While this is far short of the total operating system memory used by the program, which includes dynamic variable, stack and other auxiliary memory allocations, it is a good measure of how large your job memory partition needs to be. This is particularly true since 6.3.1518 when the string stack was moved to dynamic memory. A reasonable rule of thumb would be to set your partition size to 300-500K larger than the largest /MEMREQ value for your application. Use DIR /MEMREQ/SSIZE to find the largest values; don't forget to also check the LIT files in SYS: since some of them may have large requirements.


EDIT$ Enhancements

Enhancements to EDIT$(expr,flags) function:

• Add new flags &h0040 (unquote) and &h0080 (exempt quoted characters).

•Define symbols in ashell Define symbols in ashell.def for the various EDIT$ flags:

Symbol | Value | Description
EDITF_SPTB | &h0002 | remove spaces and tabs
EDITF_CTLS | &h0004 | remove chr(127) & chr(0)-chr(31) except TAB
EDITF_SPTBL | &h0008 | remove leading spaces and tabs
EDITF_SPTB1 | &h0010 | shrink spaces & tabs to one space
EDITF_SPTBR | &h0020 | remove trailing spaces and tabs
EDITF_UNQT | &h0040 | unquote (and reduce "" to "). EDITF_UNQT performs two operations: 1) if the first and last character, after any other processing (such as removal of leading/trailing spaces and tabs) are both double quotes ("), then are removed. 2) Any remaining double double-quotes ("") which are not preceded by a single double-quote are reduced to a single double-quote ("), unless the string has been reduced to a single pair of double double-quotes ("").
EDITF_EXQT | &h0080 | limits action to outside matched quotes. Exemption for quoted strings allows for multiple quoted subsections. This works well with JSON documents, which may contain many individually quoted strings, yet it may be convenient to remove all the whitespace not within those quoted strings.

Examples

S$ After EDIT$(S$,EDITF_SPTB+EDITF_EXQT)

--------------------- ------------------------------------------

"name" : "v1 v2" "name":"v1 v2"

"name" : v1 v2 "name":v1v2

"name : v1 v2" ] "name : v1 v2"]

"6"" ruler" "6"" ruler"

S$ After EDIT$(S$,EDITF_UNQT)

--------------------- ------------------------------------------

"6"" ruler" 6" ruler

"6"" ruler":$1.99 "6"" ruler":$1.99

In the last example above, the outer quotes were not removed because they didn't completely enclose the string, and the "" was not reduced to " because it followed a " character.


1533 — 25 October 2016

1533.2 | Fix | Compiler edit 789: revise compiler edit 763 so that it only uses the 48 bit integer format for large numeric literals that are either explicitly tagged with the "L" suffix or with the hex (&h) or octal (&o) prefix. Previously it was using the new format for large numeric literals expressed in exponential or decimal notation, which was causing unexpected backwards compatibility problems when compiling under 6.3 and running under 6.2.
1533.1.2 | Fix | Runtime: close a loophole in the space() function whereby it could cause an invalid memory reference if the first space(x) call was with x=0. This was noticed in VUE on an initial ^B command; problem introduced in 1532.0.
1533.1.1 | Fix | Compiler edit 788: fix conflicts between /PX, ++IFLBL, and PRIVATE function declarations. /PX was removing functions that were only called within ++IFLBL blocks testing for the existence of the function. And ++IFLBL was not seeing PRIVATE function labels.
1533.0.2 | Add | Language: .SORT $mlist() now implemented. .SORT $kids() sorts according to the collating sequence, just as the ordered map does.
1533.0.1 | Add | Language: .SPLICE Parameter DSTPOS specifies the splice position in the destination array.

Subtopics

.SPLICE Parameter DSTPOS


.SPLICE Parameter DSTPOS

Language enhancement: .SPLICE statement now allows an optional fourth parameter to specify the splice position in the destination array:

.SPLICE $dst(), $src(), count, dstpos

where dstpos may be:

Value | Meaning
-1 (default) | indicates end of the $dst() array
0 | indicates the start of the $dst() array
n (n > 0) | indicates after the nth item in $dst() array

Note that this option only applies when the destination parameter is expressed as a base array, as in the above example. Attempting to specify the dstpos parameter when the first parameter is an iterator or other individual element reference will result in a syntax error.

Examples

If $kids() contains the list: "john", "fred", "sally", "pilar" and $pets() contains the list: "dog", "cat", "mouse", "lizard" then:

.SPLICE $kids(), $pets(), 1, 0

would splice "dog" to the start of the $kids() array.

.SPLICE $kids(), $pets(), 3, 2

would splice the first 3 pets ("dog", "cat", "mouse") after the 2nd kid, i.e. in between "fred" and "sally".

.SPLICE $kids(), $pets(), 0, -1

would be the same as

.SPLICE $kids(), $pets()

i.e. would splice all of the pets (count=0), to the end of the kids (-1).

.SPLICE $kids(), $pets(), 0, 0

would splice all of the pets to the start of the kids array.


1532 — 20 October 2016

1532.6.2 | Refine | Runtime: the .splice statement now accepts limited use of a reverse iterator, but only when the count is 1.
1532.6.1 | Refine | .SPLICE statement: the third argument, count, can now be any numeric expression; previously only a variable was allowed. This was an unnecessary compiler restriction, there was no such limitation in the runtime system.
1532.5 | Fix | Close memory handle leak which was causing a memory handle to be used up whenever an INPUT operation within an SBX required more than 4K bytes. Same fix as 6.2.1428.3.
1532.4.2 | Fix | Fix bug causing corruption of the memory handle table during SBX calls involving collections and/or recursion. Introduced in 1532.0.
1532.4.1 | Fix | Windows: closing a sequential file that had been associated with a socket via MX_FILESOCK. Was sometimes crashing the session.
1532.3 | Fix | Compiler edit 785: an array received by reference in a function definition may now be given a default value of .NULL in order to make the parameter optional (consistent with indirect functions). Note that prior to edit 765 the compiler allowed a default value of "".
1532.2 | Fix | Compiler edit 784: ++PRAGMA GLOBAL_BEGIN crashing compiler if /PX switch used.
1532.1.5 | Refine | ATE: the FTP transfer protocol and ports now default based on the terminal transport protocol and port if the "Link to Transport Settings" option is set. This is mainly for the benefit of the ATE Web Connect protocol where it is easy, and possibly desirable, to not specify such settings.
1532.1.4 | Refine | COMPIL.LIT / COMPLP.LIT 1.1(133): /IGOO switch now recognized. This was actually implemented in the internal compiler 779 update when the INCLUDE_GLOBAL_ONCE_ONLY pragma was added.
1532.1.3 | Fix | Standalone compiler edit 783: (a) the -px switch is now recognized. Previously it was being treated the same as -p (which avoided the problem with Private functions) but also failed to deliver the "tree-shaking" (unused routine removal) benefits; and (b) the -igoo (treat all ++include as ++include'once) switch now supported.
1532.1.2 | Fix | Compiler edit 783: /px switch was conflicting with Private routines, in some cases removing them from the RUN even if they were being called.
1532.1.1 | Fix | Close loophole allowing corruption of the string stack when processing a very large string constant in an expression.
1532.0.5 | Fix | Update check-for-updates module. It was reporting availability of 6.2 version on first try before updating itself.
1532.0.4 | Fix | Add missing SftTree_IX86_U_75.dll to distribution.
1532.0.3 | New | Add CMD:TESTCACHE.CMD as a convenience to make it easy to test the webcache. It contains the commands SET WEBCACHE REPO http://www.microsabio.net/testrepo and SET WEBCACHE ENABLE,ALL,ATE.
1532.0.2 | Refine | Webcaching of DLLs: webcache option can now be enabled after a failed attempt to load the XTREE or XTEXT dll. Previously XTREE and XTEXT gave up after the first failed attempt so wouldn't benefit from activating webcache and retrying. http://www.microsabio.net/testrepo now contains copies of the various DLLs that can be web-loaded.
1532.0.1 | Refine | Runtime: remove limit on memory handles—previously 500—to to support very large MLIST structures, which use a lot of memory handles.


1531 — 05 October 2016

1531.0.6 | ZTXFER.LIT 1.4(108) now supports /ATE switch to force alternative transfer protocol—i.e. using ATE terminal channel. This was already automatic for transfers between an ATE client and a Windows server, but now can be forced in other situations. For example, under UNIX, FTP/SFTP transfers may be blocked by some security or other obstacle, while the ATE terminal channel would work.
1531.0.5 | Bug fix: assignment to DIMX type B or type I array elements using INPUT, READ, or XGETARG{S}, wasn't working properly due to a failure to pick up the correct element size from the descriptor of the array, which differs between static and DIMX arrays. This was a very longstanding problem—may go back to the original implementation of DIMX arrays—but was easily overlooked until 6.3.1516 when the B6 and I6 variables were introduced; because prior to that, the destination variable size was defaulting to 4 bytes when not set to another valid size. For the B2 and I2 cases, this would have assigned the correct value but also overwritten the next 2 bytes in memory—i.e. the next element in the array. Since 6.3.1516, it was doing nothing, resulting in a received value of zero.
1531.0.4 | New AG_WEBCACHE command gets/sets webcache options from host.
1531.0.3 | Add the following flags to ashell.def for MX_WEBCACHE: WCDF_DLL &h00000010 download DLLs to bin or webcache WCFG_ALL &h000000FE all flags except WCDF_ENABLE
1531.0.2 | New SET.LIT 1.2 Flags DLL, ALL, and ATE.
1531.0.1 | A-Shell/Windows runtime enhancement: Webcache feature now supports most A-Shell/Windows DLLs. These are downloaded to the A-Shell executable directory if it is writeable; otherwise they are downloaded to the webcache directory.

Subtopics

SET.LIT 1.2 Flags DLL, ALL, and ATE

AG_WEBCACHE


SET.LIT 1.2 Flags DLL, ALL, and ATE

SET.LIT 1.2(158) adds new flags DLL, ALL, and ATE.

DLL flag causes A-Shell to attempt web download of missing DLLs from repository; if possible, it downloads them directly into the executable directory, else into the webcache directory.

.SET WEBCACHE ENABLE,DLL

ALL flag sets all options but not ENABLE itself, equivalent to PROG, OPENI,LOOKUP,DLL and any others to come in the future.

.SET WEBCACHE ENABLE,ALL

ATE pseudo-flag tells SET to pass the webcache flags and repo info to the ATE client. Note that if you want to assign different options and/or repository directory to ATE, use the following sequence:

.SET WEBCACHE REPO <repo for ATE>

.SET WEBCACHE ENABLE,<options...>,ATE ! forward options & repo to ATE

.SET WEBCACHE REPO <repo for server>

.SET WEBCACHE ENABLE,<options...> ! set server options only


AG_WEBCACHE

New AG_WEBCACHE (108) command to get/set webcache options from host:

? tab(-10,AG_WEBCACHE);op{,flags{,url}};chr(127);

Parameters

op

0 to retrieve and 1 to set. On retrieval, the returned string will contain "flags,url" (current webcache flags and repo url).

flags

is a decimal number containing the WCDF_xxx flags

url

if specified, is the web directory for the repository.

Example

? tab(-10,AG_WEBCACHE);"1,";(WCDF_ENABLE or WCDF_ALL); ",http://www.myrepo.com/app1";chr(127); ! enable; set repo

? tab(-10,AG_WEBCACHE);"1,0";chr(127); ! disable

? tab(-10,AG_WEBCACHE);"0";chr(127); ! retrieve

? tab(-10,AG_WEBCACHE);chr(127); ! same (retrieve)

input line, response$ ! input flags,url


1530 — 05 October 2016

1530.1.2

ATE refinements related to use of the ashell-ate-URL scheme to launch ATE from a web page. These include:

•The MIAME environment variable is now always set to match the location of the miame almost always the case anyway, except that when launched from a URL link, visibility restrictions on the environment between Windows and the browser were resulting in it reverting to C:\VM\MIAME.always the case anyway, except that when launched from a URL link, visibility restrictions on the environment between Windows and the browser were resulting in it reverting to C:\VM\MIAME.

•The Cache and PermCache The Cache and PermCache directories now default to %MIAME%\Cache and %MIAME%\PermCache, respectively, if not set. This was a potential issue when building a minimal configuration on the fly from the URL.

• When building the ATE configuration on the fly, you can define pseudo configuration values LoginSBX=<xcallname> and WebRepo=<url dir> to cause ATE to check the web repository for the custom login dialog.

1530.1.1

Bug fix, XFUNC$(): using XFUNC$() in a string expression was corrupting the string stack, resulting in somewhat unpredictable string results. Problem was introduced with the auto-expanding string stack in 6.3.1518.

1530.0.6

XTREE enhancement: column ordering for all the columns (up to the max of 100) can now be saved when using the TreeID mechanism with the XTUCFG_COLORD bit set in the XTR'USRCFG field. Previously the limit was 31 columns, which remains the limit when using the XTR'COLORDER() array method without the TreeID option.

1530.0.5

XTREE enhancement: extended checkbox columns may now be extended to a second degree by adding a second "+" (e.g. T++ or T3++). This adds a 3-state checkbox to the header of the column which is automatically set to the checked state if all the boxes in the column are checked; the unchecked state if all the boxes are unchecked, or the indeterminate state if there is a mixture (or if all of the boxes are indeterminate). Clicking the checkbox in the header cycles through the check-all, uncheck-all, set-all-to-indeterminate (if 3-state), and back to the origional mixed state (if applicable).

1530.0.4

XTREE enhancement: 3-state editable checkbox columns now support the extended mode (T3+) which adds the ability to check-all (^A), uncheck-all (^B) and undo (^Z).

1530.0.3

New release of the DLL underlying XTREE (SftTree_IX86_U_75.DLL, previously SftTree_IX86_U_70.DLL)

1530.0.2

Implemented two New INSTR Flags.

1530.0.1

Run-time enhancement: quoted native filespecs now supported with RUN, e.g. .RUN "/vm/miame/webcache/hello.run"

Subtopics

New INSTR Flags


New INSTR Flags

Two new flags implmeneted in INSTR:

Flag | Value | Description
INSTRF_ANY | &h01000000 | Treat pattern as set of characters; match first one that appears in subject.
INSTRF_ANYQT | &h02000000 | Same as INSTRF_ANY but ignores characters in subject between matching quotes.

Note that unlike all of the other INSTR() flags, these do not actually use the REGEX library. They are instead based on the standard C function strpbrk(). For example:

PRINT INSTR(1, "DSK0:ABC.RUN /X", ";/ ", INSTRF_ANY)

Of the three characters in the pattern (";/ "), the first to occur in the subject is the space at position 13.

The above is equivalent to the REGEX character set pattern "[;/ ]"; it simply eliminates any doubts about REGEX syntax for special characters. But the INSTRF_ANYQT version is much harder to implement using REGEX.


1529 — 30 September 2016

1529.0.4 | Add new LIT file WEBRUN.LIT
1529.0.3 | Add subroutine MX_WEBCACHE.
1529.0.2 | Add support to SET.LIT for WEBCACHE.
1529.0.1 | Implement major new feature WEBCACHE for auto-loading required files from web.

Subtopics

WEBCACHE

SET.LIT for WEBCACHE

MX_WEBCACHE

WEBRUN.LIT


WEBCACHE

A-Shell runtime enhancement: auto cache/download of files from a web directory if not found in the local search path. Downloaded files are cached in the directory %MIAME%/webcache, which is checked first—as in a web browser—to avoid the overhead of unnecessary web accesses.

The feature is referred to under the generic umbrella of "WEBCACHE" and may be enabled and configured via a new SET.LIT option and/or a new MIAMEX function (both described below).

Option flags determine which types of files are subject to the feature. By default it applies to images and any other kind of file operation that currently supports automatic lookup in the cache and permcache directories. Additional file/type options:

Option | Description
PROG | programs (RUN, LIT, SBX)
OPENI | files being opened for sequential input
LOOKUP | files reference by LOOKUP statement or XCALL SIZE

Currently only a single web directory at a time is supported, although it is conceivable that multiple directories and/or trees may be implemented in the future.

The webcache directory, like the permcache directory, is not auto-cleared at the end of the session. But like a typical web browser cache, it can be cleared with a command. Individual files or files matching a pattern can also be cleared. Also, as with a typical web browser, the existence of a file in the cache short-circuits any web lookup for that file; there is no automatic comparison of file sizes or dates between the cached copy and the web copy (because this would completely undermine the performance benefit of the cache). So you have to clear the cache in order to get a refreshed copy from the web repository.


SET.LIT for WEBCACHE

SET.LIT 1.2(157) now supports options to manage and configure the new webcache feature:

Option | Description
(blank) | display current webcache settings
? | display usage information
ENABLE | enable
DISABLE | disable
CLEAR | erase all files in local webcache
REFRESH <spec> | remove files from cache matching spec
REPO <url> | set the web repository directory
<option,...> | set options...

options:

Option | Description
PROG | activate webcache for programs (RUN, LIT, SBX)
OPENI | activate webcache for sequential input file opens
LOOKUP | activate webcache for LOOKUP operations


MX_WEBCACHE

New MIAMEX MX_WEBCACHE (188) function to related to the web cache feature:

The syntax for MX_WEBCACHE is dependent on opcode. For each opcode, add the opcode and what is shown in the "Syntax" column to the statement:

xcall MIAMEX, MX_WEBCACHE,

Opcode | Syntax
0 | status
1 | status
2 | status, url$
3 | status, url$
4 | status, url$, localfile$
5 | status {,wildspec$}

For example, the syntax for opcode 3 would be:

xcall MIAMEX, MX_WEBCACHE, 3, status, url$

Parameters

opcode (num) [in]

Determines operation (see below).

status (signed int) [in/out]

Sets or returns options, or returns status codes (see below).

url$ (string) [in]

Specifies a web directory for ocodes 2 and 3, and a fully qualified file URL for opcode 4. Currently the only URL schemes supported are http:// and https://. An optional :port may be appended to the end. Examples:

http://www.mysite.com/webrepo

http://www.mysite.com/webrepo/myfile.run:10080

https://www.mysite.com/my web repository

Opcodes

Opcode 0 retrieves the current webcache options in status. Status flags (defined in ashell.def) :

Symbol | Value | Description
WCDF_ENABLED | &h00000001 | web cache enabled (else disabled)
WCDF_PROG | &h00000002 | download/cache programs (RUN,LIT,SBX)
WCDF_OPENI | &h00000004 | download/cache files on open for input
WCDF_LOOKUP | &h00000008 | download/cache any file on LOOKUP or SIZE.SBR

Opcode 1 sets the webcache options to the value status.

Opcode 2 and 3 retrieve and set webcache url (web directory), respectively. Status will return 0 for success.

Opcode 4 performs a manual download from the specified url$ to the specified localfile$. If the url$ is just a file.ext and the webcache url directory has been previously set, then the two are combined to form the complete source url. If localfile$ is "", the source file.ext is used. If localfile$ does not contain a directory, then the local webcache directory (%MIAME%\webcache) is used. Returned Status will equal the # of bytes downloaded if successful, else an error code:

Status | Meaning
-1 | Unsupported URL scheme (e.g. not http:// or https://)
-2 | Specified URL does not contain filename (Opcode 2)
-3 | URL too long
-4 | Unable to connect to host web server
-5 | Error sending HTTP GET command to server
-6 | Error in local webcache directory\file spec
-7 | Response from web server missing header terminator
-8 | Response from web server not recognizable
-9 | Transmission problem receiving header
-### | HTTP response error code (converted to negative)

Opcode 5 clears the local webcache directory. If the wildspec$ parameter is specified and non-blank, only those files matching the wildspec$ will be cleared; otherwise all of the files in the cache will be cleared. Returned status will equal the number of files removed from the cache.


WEBRUN.LIT

Add new LIT command for WEBCACHE support:

.WEBRUN url {args}

Front-end to RUN.LIT which downloads the specified program from url into the webcache directory and then runs it, passing any args to it. If url contains spaces, it must be quoted, and if any args are specified, there must be at least one space between url and the args. If the url filename has no extension, .run is assumed. It also enables the webcache feature and all options (equivalent to SET WEBCACHE ENABLE,PROG,OPENI,LOOKUP) and sets the default URL based on URL given (minus the filename).

Note that this command also bypasses the normal search path—i.e. will ignore a copy of the target program in the current [p,pn], [p,0] or [7,6] directories.

Examples

.WEBRUN http://www.mysite.com/app1/myprog

This command:

• enables all webcache options

• sets the repo to http://www.mysite.com/app1

• checks local webcache for myprog.run; if not there, tries to download it from the URL.

• tries to execute it from the webcache dir.

.WEBRUN "http://www.another site/app2/prog2.run" /demo

Similar to previous example except that it also passes the command line switch "/demo" to the target program prog2.run.


1528 — 27 September 2016

1528.1.3 | Refinements to the MLIST .SPLICE operations.
1528.1.2 | Bug fix, runtime: passing an iterator value to a function was generating a bogus parameter type mismatch error. Introduced in 1528.
1528.1.1 | Bug fix, compiler edits 780 and 781: fix misc parsing problems related to passing/receiving $$i.sublist, ordmap, and ordmapm arrays.
1528.0.4 | Compiler enhancement (compiler edit 779) adds pragma ++pragma INCLUDE_GLOBAL_ONCE_ONLY <boolean> . When enabled, ++include is treated as ++include'once, except when it occurs inside a function or procedure. In such cases, it is likely that you are intentionally including an extra copy of some map statements.
1528.0.3 | Compiler enhancement (compiler edit 778) adds auto-defined macros ABC_CURRENT_ROUTINE$ and ABC_CURRENT_MODULE$. These equate to the current function/procedure name (or "" if none), and the current module filename (file.ext). Both may be useful in standardized error reporting.
1528.0.2 | Compiler enhancement (compiler edit 777) adds New PRAGMAs.
1528.0.1 | Language enhancement (compiler edit 776) adds Indirect Function Calls.

Subtopics

Indirect Function Calls

New PRAGMAs


Indirect Function Calls

A reference to a function or procedure may now be passed as an argument to another function or procedure. This is an advanced technique that is mainly useful in multi-level (often recursive) algorithms consisting of a generic intermediate layer and a specific lower layer which may need to be customized for each particular problem. The indirect function call technique allows you to effectively customize the generic intermediate routine without actually having to modify it. (Instead, you pass your custom routine to it, which it then calls indirectly to do the parts of the algorithm which you want to customize.)

The custom routine in this scenario is sometimes referred to as a "callback routine", since the idea is for the generic intermediate routine to call your routine back to perform the part of the algorithm requiring customization.

For example, when parsing an XML file, you may want to employ a generic routine to walk the tree, but a custom routine to process nodes that meet some criteria. Because of the recursive nature of the routine to walk the tree, it is difficult for it to exit back to your application each time it hits one of the target nodes, without losing its position and ability to continue to the next node. The solution is to design the generic routine to accept a callback routine to be called for each target node. Each application can then use the generic routine in a different way by passing a different callback routine to it.

The scheme consists of three parts:

1. The Callback Routine.

This is a normal function or procedure.

2. The Generic/Intermediate Routine

This receives the callback reference and makes calls to the callback routine. In this routine, the parameter to receive the indirect/callback reference must be defined as follows:

Procedure Foo( ..., @fn'cb() as lblref, ... )

For functions, the formal name must follow the standard naming rules, i.e. start with "Fn'" and end with $ if the functions returns a string value. In all cases it must start with "@", and end with the "as lblref" clause. An empty pair of parentheses, as in the example above, is optional. (Parameters to be passed to the indirect routine are not specified in the declaration.) Beyond that, the name may be anything, for example:

@fn'callback as lblref

@FN'PROC$ AS LBLREF

@Fn'Custom$() as lblref

@myproc() as lblref

The above parameter declarations would apply to a numeric function, two string functions, and a procedure, in that order.

Inside the intermediate routine, you can call the callback routine using the name specified in the declaration. For example:

call fn'cb(arg1,...) ! call actual callback with actual args

Note: unlike nearly all other formal parameter types, lblref parameters default to .NULL rather than "" if the caller does not supply the actual parameter. This allows you to test whether the function reference was supplied, e.g.

if .ISNULL(fn'cb) then ! if myproc not passed

call my'default'proc(...) ! use a default routine

else

call fn'cb(...) ! else call the passed routine

endif

Within the intermediate routine, if you need to pass the callback routine indirectly again to another routine, or recursively to yourself, then retain the @ prefix, e.g.

Procedure Foo(..., @fn'cb() as lblref, ...) ! intermediate rtn

...

call Foo(...,, @fn'cb(), ...) ! pass callback again indirectly

...

endprocedure

3. The call to the generic/intermediate routine

In this you pass the reference to your callback routine as a parameter. Here you must precede the actual callback routine name with "@" and use an empty set of parens, e.g.

Function Fn'Bar(...) ! actual callback routine

...

Endfunction

...

call Foo(...,@Fn'Bar(), ...) ! passing callback to intermediate Foo()

Note: if you fail to specify the "@" prefix when passing the callback routine to the intemediate routine, it will still be syntactically and semantically legal, but the result will be completely different. To clarify, consider the following two examples:

call Foo(Fn'Bar())

call Foo(@Fn'Bar())

In the first call, the function Fn'Bar() is evaluated first and its return value is passed to the procedure Foo(). In the second call, a reference to the Fn'Bar() function is passed indirectly to the procedure Foo(), which will then be able to call that function without knowing its real name.

Examples

The following example illustrates the scheme using a generic intermediate SOSLIB routine Fn'Dir'Scan() which scans a directory tree recursively looking for files whose names match a pattern. For each file that matches, it calls your custom routine with the filespec so that you can perform some processing on it. By using the callback technique, the generic recursive directory scanning logic can be re-used without modification in many different applications; the customized callback routine allows each application to process the files differently.

Function Fn'Dir'Scan(dir$ as s260, wild$ as s100, &

@procfile() as lblref) as i4

do

file$ = <next entry in directory>

if <file$ is a normal file and matches wild$>

Fn'Dir'Scan += 1 ! count matching files

call procfile(entry$) ! callback routine for file

elseif <file$ is a subdir>

count += Fn'ProcDir(file$, wild$, @profile()) ! recursion

endif

loop until <end of directory>

EndFunction

To use the Fn'Dir'Scan routine, we need to define our callback routine and pass it by reference to the Fn'Dir'Scan routine. For a simple example, here's a callback routine that just prints the file name:

Procedure Show'File'Info(fspec$ as s260:inputonly)

print fspec$

EndProcedure

Now we can use the generic Fn'Dir'Scan() function to print the names of the .bp files in all of the subdirectories of c:\vm as follows...

count = Fn'Dir'Scan("c:\vm", ".bp", @Show'File'Info())

Later in the same app we might want to copy all the matching files to a backup directory. We can use the same Fn'Dir'Scan() routine, but supply a different callback function...

Procedure Backup'File(fspec$ as s260:inputonly)

xcall MIAMEX, MX_COPYFILE, fspec$, ...

EndProcedure

...

count = Fn'Dir'Scan("c:\vm", "*.bp", @Backup'File())


New PRAGMAs

Compiler enhancement (edit 777) adds these new pragmas:

++PRAGMA ASHELL_EXTENSIONS <boolean>

++PRAGMA PRE_PROCESS <boolean>

++PRAGMA EXTENDED_PRE_PROCESS <boolean>

Each of above enables/disables the switches /X:2, /P, and /PX respectively. The <boolean> argument is optional and defaults to "TRUE".

Note that each of the above must be placed before any other code, except for comments, ++pragmas, ++IFxxx conditionals, and the PROGRAM statement.

Also note that this change sets the default for all pragmas accepting a <boolean> argument to "TRUE". (Previously some of them required an explicit argument while others did not.) So for example, the following two are now equivalent:

++pragma ERROR_IF_NOT_MAPPED

++pragma ERROR_IF_NOT_MAPPED "TRUE"

Previously, the first one would have triggered an invalid argument error.


1527 — 14 September 2016

1527.0.7 | ATE refinement: The disconnected message box no longer displays when the disconnect was triggered by the menu disconnect option.
1527.0.6 | New built-in system dot function: .INSTRR
1527.0.5 | TELNET.LIT 2.2(146) enhancement to support the new ashell-ate custom URL scheme. Details to follow.
1527.0.4 | ATE Enhancement: the -atecfg command line switch used to pass the configuration name to ATE now supports a compound argument up to 1024 bytes long which can be used with the ashell-ate custom URL scheme to pass an ad-hoc configuration as a set of value=attrib pairs. Details of this feature will be documented later.
1527.0.3 | Bug fix, AUI_CONTROL: MBF2_STICKY was leaving 1 pixel between the right edge of some controls and the border of the parent.
1527.0.2 | Bug fix, AUI_CONTROL: Using CTLOP_CHG to change the text associated with a control (including the image spec) was truncating the internally stored text for longer text strings. This would typically only become apparent after later manipulations were performed on the control, such as resizing it. (Same patch as 1428.1)
1527.0.1 | AG_WALLPAPER enhancement: New AG_WALLPAPER Parameter DLGID parameter allows wallpaper to be applied to dialogs.

Subtopics

AG_WALLPAPER Parameter DLGID

.INSTRR


AG_WALLPAPER Parameter DLGID

AG_WALLPAPER enhancement: A new dlgid parameter on the command allows wallpaper to be applied to dialogs:

? TAB(-10,AG_WALLPAPER); imagespec$ {,flags {,dlgid}}; chr(127);

For dialogs, flags must be 0. The only valid operation is to set the wallpaper to the dialog; it is destroyed when the dialog is deleted. But unlike the case with main window wallpaper, for dialogs, the imagespec$ can be any image type recognized by AUI_CONTROL. JPG is probably the best option here.

The dlgid parameter may either be the numeric or alphanumeric identifier for the dialog. If dlgid is zero or omitted, the command works on the main window as before.

In most cases, you will want to create the dialog with the bgc parameter set to RGB_TRANSPARENT, else the background of static text controls will cover that portion of the wallpaper.


.INSTRR

Language enhancement (compiler edit 774) : New built-in system dot function:

.INSTRR(spos,string,pattern)

.INSTRR() is similar to INSTR() except it searches in reverse, e.g. it searches the string for the pattern, starting at the specified spos and working backwards towards the beginning of the string. The return value is the position of the last match—i.e. first match working backwards, with 1 indicating the first character of the string and 0 indicating no match.

Unlike INSTR(), .INSTRR() supports both positive and negative starting positions, with negative values counting from the end of the string—e.g. -1 starts the search at the end of the string. However the return value is always >= 0—i.e. position starting from the beginning of the string.

Also unlike INSTR(), .INSTRR() does not support the 4th argument used for regular expression searches.


1526 — 10 September 2016

1526.0.4 | Language enhancement (compiler edit 773): New IFELSE Functions.
1526.0.3 | MIAMEX functions MX_GETTRACE and MX_SETTRACE updated to support the TROP_JOBLCK (&h000100000000) TRACE flag. Note that this bit is beyond the 32 bit range of the typical 32 bit flags word, so you need to use B5, B6, I6, or F6/F8 to retrieve or set this bit.
1526.0.2 | SET.LIT 1.2(156) updated to support TRACE flags JOBLCK and EXEC, which were added in 6.3.1518.0.
1526.0.1 | Add MIAME.INI Trace Option JOBLCK.

Subtopics

Trace Option JOBLCK

New IFELSE Functions


Trace Option JOBLCK

New MIAME.INI trace option: TRACE=JOBLCK causes all unresolved lock/unlock operations on the jobtbl.sys file to be traced in the file jobtbl.lck. The intent here is to make it easier to debug and resolve a rogue condition whereby a process has a lock on jobtbl.sys preventing other users from getting in or out of A-Shell. (Under Linux you can use the lslk utility to see who has a lock on the file, but under AIX this appears to be nearly impossible, and under Windows it may be difficult.)

The jobtbl.lck file is created in the same directory as jobtbl.sys, and consists of human readable ASCII text lines in the following format:

pid,op,recno

where pid is the process id, op is either "lock" or "unlock", and recno is 0 for the jobtbl header, else a number indicating the jobtbl record for that job number. For example:

2415,lock,5

3723,lock,15

2415,unlock,5

3724,unlock,15

The above case indicates the following chronology:

process 2415 locked the jobtbl record for job #5

process 3723 locked the jobtbl record for job #15

process 2415 unlocked the jobtbl record for job #5

process 3723 unlocked the jobtbl record for job #15

Since at this point the locks and unlocks match, on the next operation, the file will be truncated and started over again.

If the option is enabled and you get a "unable to access JOBTBL.SYS" error, you can then display this file to hopefully identify which processes have locks on the file and can then investigate or kill those processes.

Note: a stripped-down version of this feature was added to 6.2.1428.0.


New IFELSE Functions

Language enhancement (compiler edit 773) adds the built-in system functions:

IFELSE(cond, expr1, expr2)

IFELSE$(cond, expr1, expr2)

Each takes a conditional expression (cond) and two value expressions (expr1 and expr2). If the conditional expression evaluates to TRUE, then the function returns the value of expr1, else it returns the value of expr2. IFELSE returns a numeric value and IFELSE$ returns a string value.

These functions are conveniences which can often eliminate the need for a temporary variable or duplication of statements that differ only by a single either/or choice. For example, consider a case where you want to print a value with one of two masks depending on whether the value is less than 1. You might code it like this:

if VALUE >= 1 then

PRINT VALUE USING "#####"

else

PRINT VALUE USING "#.###"

endif

With the IFELSE$() function, you can eliminate the IF statement and reduce the two PRINT statements to one:

PRINT VALUE USING IFELSE$(VALUE>=1,"#####","#.###")

Or, in the case of larger statements where you are more likely to introduce temporary variables than to repeat variations of the statement, IFELSE() can eliminate the need for a temporary variable, e.g.

if flag'disable then

CSTATE = MBST_DISABLE

else

CSTATE = MBST_ENABLE

endif

xcall AUI, AUI_CONTROL, CTLOP_ADD, CTLID$, CTEXT$, CSTATE, CTYPE$, CMD$, FUNC$, ...

The above can be reduced to a single statement using IFELSE():

xcall AUI, AUI_CONTROL, CTLOP_ADD, CTLID$, CTEXT$, ifelse(flag'disable,MBST_DISABLE,MBST_ENABLE), CTYPE$, CMD$, FUNC$, ...


1524 — 01 September 2016

1524.0.4 | Bug fix, BASORT: sorting a file with BASORT may have crashed A-Shell if the filespec was longer than 80 characters.
1524.0.3 | Bug fix: close an obscure loophole in the PRINT routine in which a device error during printing a CRLF pair might fail to raise the BASIC error (even though it displayed a "Device error" message.)
1524.0.2 | New subroutine MX_FILESOCK binds a TCP socket to a sequential file channel so that PRINT #CH and/or INPUT #CH transfers data over the socket rather than to/from the file.
1524.0.1 | New Special File Name .NULL may be used with sequential files to open a file which is not connected to anything.

Subtopics

Special File Name .NULL

MX_FILESOCK


Special File Name .NULL

New feature: special file name .NULL may be used with sequential files to open a file which is not connected to anything. For example:

OPEN #1, .NULL, OUTPUT

OPEN #2, .NULL, INPUT

For output, .NULL is equivalent to the device /dev/null under UNIX and NUL under Windows, i.e.any data output to the file is just discarded. For input, .NULL acts like an empty input file (returns EOF on the first input attempt).

The ability to associate an output file channel with a null device adds to the flexiblity of the PRINT #CH statement, since depending on the value of CH and what file it is associated with, the statement can output to the screen (if CH=0), a disk file, or nothing at all. But the feature is even more useful in conjunction with the new MX_FILESOCK mechanism (see next).


MX_FILESOCK

New MIAMEX function: MX_FILESOCK (187) binds a TCP socket to a sequential file channel so that PRINT #CH and/or INPUT #CH transfers data over the socket rather than to/from the file.

xcall MIAMEX, MX_FILESOCK, ch, socket, status

Parameters

ch (num) [in]

must be a file channel (> 0) open for sequential input or output. Typically you would open the file using the .NULL filespec as described in the previous edit note.

socket (num) [in]

must be a valid socket opened via TCPX.SBR.

status (signed num) [out]

returns 0 for success, else error.

If ch was open for output, then after the successful completion of the MX_FILESOCK call, PRINT #CH statements will output to the socket instead of the file. Similarly, if ch was open for input, then INPUT #ch statements will read from the socket.

Note that while sockets are bidirectional, sequential file channels are not, so if you want to both input and output to the socket this way, you'll need to open two file channels and bind them both to the same socket with two separate MX_FILESOCK calls.

Once the file channel is bound to the socket, closing the file channel will also close the socket.

To simplify the operation of opening the file and socket and binding the two together, a pair of functions has been added to the SOSFUNC: library:

Fn'FileSock'Out(ch, socket, server$)

Fn'FileSock'In(ch, socket, server$)

See the fnfilesock.bsi source code in the [907,10] directory of the SOSLIB for details, including a sample/test routine.


1523 — 30 August 2016

1523.0.2 | SUBMIT.SBR refinement: subscripted string arguments are now supported as they are in most other SBRs.
1523.0.1 | Language/compiler (edit 770) enhancement adds Private Attribute for Functions and Procedures.

Subtopics

Private Attribute for Functions and Procedures


Private Attribute for Functions and Procedures

Language/compiler (edit 770) enhancement: Private attribute for functions and procedures. Function and Procedure definitions within ++include modules may now be preceded with the keyword PRIVATE to make them invisible outside of that ++include file. This is analogous to the use of the PRIVATE keyword to declare a variable as being visible only within the ++include file. For example:

PRIVATE FUNCTION FN'TEST() AS F6

....

ENDFUNCTION

The two most likely motivations for declaring a function or procedure to be private are:

• As a namespace mechanism to prevent conflicts with procedures of the same name in other include files. Previously, the only way to avoid this risk would have been to append or prepend some module-specific text (perhaps the module name) to the routine name, but this ends up making your routine names overly long, making them difficult to type and read.

• As a way of making the code easier to understand or debug later. (Eliminating the possibility that the routine is called from anywhere outside the current module eliminates the need to consider impossible scenarios that would otherwise be difficult to rule out without searching every possible file that could use this module.)


1522 — 13 August 2016

1522 | Language enhancement adds bidirectional linked list MLIST.
 | (no other changes for this numbered version)

Subtopics

MLIST


MLIST

Language enhancement adds new collection type:

MLIST(varstr)

MLIST(varx)

MLIST (short for "Multi-level LIST") is a bidirectional linked list, with the added feature that each element may contain a link to a child MLIST. Aside from the links, each element may contain a variable length string (varstr) or blob (varx). The MLIST is effectively a kind of tree structure, useful for representing a variety of real-world data such as disk directories and XML/JSON documents, where the ability to maintain a particular order and to efficiently insert, delete, and splice elements or branches at arbitrary points is required.

Unlike the ORDMAP and ORDMAPM collections, there is no direct access to an element by its key; there is only direct access to the first and last elements in the list, with the ability to iterate forwards, backwards, or down from there. The order of the elements in the list is preserved based on the order in which you build it.

As with other collection types, an MLIST is created with the DIMX statement:

DIMX $M, MLIST(VARSTR)

DIMX $M, MLIST(VARX)

The syntax for assigning and accessing elements is similar to that for ORDMAP, modeled on single-dimension array syntax. But instead of using string keys for the array index as in ORDMAP, the MLIST uses various special dot-variables which act as pseudo-keys. In addition, there are several new dot-statements and dot-functions and dot-members to perform operations particular to MLISTs that cannot be easily represented with existing statements and functions. These are summarized below, following by descriptions and syntax for the various operations.

Dot-Variable | Description
.FRONT | first element, e.g. ? $M(.FRONT)
.BACK | last element, e.g. ? M(.BACK)
.PUSHFRONT | add new element to front, e.g. $M(.PUSHFRONT) = X
.PUSHBACK | add new element to end, e.g. $M(.PUSHBACK) = X
Dot-Statement | Description
.POPFRONT | remove first element from list, e.g. .POPFRONT $M()
.POPBACK | remove last element from list, e.g. .POPBACK $M()
.SPLICE | splice elements from one list to other
.SORT | sort elements in list by value, e.g. .SORT $M()
Dot-Function | Description
.REF($$i) | returns a reference to iterator location, used when modifying an element by iterator, e.g. $M(.REF($$i)) = X
.BEFORE($$i) | specifies insertion position, e.g $M(.BEFORE($$i) = X
Dot-Member | Description
.SUBLIST | specifies sublist of element, e.g. $$i.SUBLIST, or $M(.BACK).SUBLIST
.KEY | $$i.KEY is equivalent to .KEY($$i)

All of the following descriptions and examples will assume the prior definition of these two MLISTs:

dimx $m, MLIST(varstr)

dimx $m2, MLIST(varstr)

Adding Elements

New elements may be added to the front or back of a list using array assignment syntax equivalent to that used for the ORDMAP collection, except instead of string keys, you must use one of the special dot-variable pseudo keys:

$m(.PUSHFRONT) = X ! add new element to front; assign value X

$m(.PUSHBACK) = X ! add new element at back; assign value x

You may also insert an element into the middle of the list using the special dot-function .BEFORE($$i). In the following example, we scan the list until locating an element whose value is "something", and then insert a new element before it:

foreach $$i in $m()

if $$i = "something" then

$m(.BEFORE($$i)) = x ! insert new element before $$i position

exit

endif

next $$i

Modifying existing elements uses the same syntax as adding or inserting new elements, except with a different set of dot variables and dot functions:

$m(.FRONT) = y ! change value of first element to y

$m(.BACK) = y ! change value of last element to y

To update the value of an element by iterator, you must use the special dot function .REF($$i) to return to updateable reference to the iterator (since $$i by itself is a read-only copy of the value of the element).

foreach $$i in $m()

$m(.REF($$i)) = $$i + "y" ! update value of each element

next $$i

Deleting Elements

Elements can be deleted by assigning the special value .NULL to them, using the element modification syntax given above. For example:

$m(.FRONT) = .NULL ! delete the first element

$m(.BACK) = .NULL ! delete the last element

foreach $$i in $m()

if $$i = "something" then

$m(.REF($$i)) = .NULL ! delete the element

exit ! always exit foreach loop

endif ! after removing an element, as it

next $$i ! may invalidate the iterator

In addition, you can use the following dot-statements to delete:

.POPFRONT $m() ! delete first element

.POPBACK $m() ! delete last element

Retrieving elements

X = $m(.FRONT) ! retrieve value of first element into X

X = $m(.BACK) ! retrieve value of last element into X

foreach $$i in $m() ! access by iterator

X = $$i ! X receives value of iterated element

next $$i

Splicing lists

One or more elements from one list can be spliced on to another using the dot-statement .SPLICE. Note no elements are actually allocated or deleted in this operation; they are just moved from the source list to the destination list. The general syntax for the .SPLICE statement is:

.SPLICE dst-list-ref, src-list-ref {, count}

If count (number of elements to move) is not specified, the operation moves all of the elements starting from the src-list-ref position. The list-ref parameters may be list base references, e.g. $m(), or they may be references to a particular element by iterator reference, e.g. .REF($$i). For example:

.SPLICE $m(), $m2()

The above case splices the entire $m2() list to the end of the $m() list. Afterward, the $m2() list will be empty (but still valid).

.SPLICE $m(), $m2(), 1

Same as the previous case except only the first element of $m2() is spliced to the end of $m().

To splice to some position other than the end of the destination, specify a position via an iterator reference. For example, to move append the 3rd and 4th items from $m2() the end of $m1()...

count = 0

foreach $$i in $m2()

count += 1

if count = 3 then ! 3rd iterated item

.SPLICE $m(), .REF($$i), 2 ! splice 3rd & 4th items

exit ! iterator corrupted after splice! must exit!

endif

next $$i

The .REF($$i) iterator technique also works for the destination, i.e. to insert at a destination other than the end of the target list. To splice from an arbitrary Xth position in the source to the Yth position in the destination, use a double-nested foreach loop:

! splice count elements from position srcpos in m1$() to dstpos in m2$

idst = 0 ! counter for dest position

foreach $$i in $m2()

idst += 1

if idst >= dstpos then ! $$i is the dst splice-to position

isrc = 0

foreach $$j in $m1()

isrc += 1

if isrc >= srcpos ! $$j is the src splice-from position

.splice .ref($$i), .ref($$j), count

exit ! must exit after splice!

endif

next $$j

exit ! must exit after splice!

endif

next $$i

Note: as with other modifications to a collection, the use of .SPLICE corrupts the iterator; thus you must exit from the foreach loop after the .SPLICE operation. (In the above example, we have to exit from both loops.)

Multi-level list operations: The sublists in an MLIST structure are themselves MLISTs, so all of the above operations work the same way on sublists. However, you do need a special dot-member, .SUBLIST, to specify when you are referring to the sublist for an element, rather than to the element as a member of the parent list.

~~~~======= !=== <this first method doesn't yet work> === ~~~~=======

There are two ways to create a sublist, both involving the use of the special .SUBLIST qualifier. The first is to splice elements from another list on to the .SUBLIST member of an element in the destination list, for example:

.SPLICE $m(.BACK).SUBLIST, $m2()

The above statement splices the list $m2() as a sublist of the last element in $m(). Note that without the .SUBLIST modifier, the $m2() list would have been spliced on to the $m() list, just before the last element.

foreach $$i in $m()

if $$i = "something" then

.SPLICE $$i.SUBLIST, $m2, 3

exit

endif

next $$i

In the above example, we scan the $m() list for an element with value "something", and then splice the first 3 elements of the $m2() list as a sublist of that target element.

~~~~~~~~~======= !=== <this method works> === ~~~~~~~~~=======

The second way to create a sublist involves passing it as a parameter to a function or procedure, which is dealt with in a separate section below, after the discussion of deleting sublists.

To delete a sublist, assign .NULL to the target element, either using one of the dot-variable pseudo-keys, or using an iterator to target the element:

$m(.BACK) = .NULL ! delete sublist from last element of $m()

foreach $$i in $m()

if $$i = "something" then

$$i.SUBLIST = .NULL

exit

endif

next $$

The above examples delete the sublist without deleting the element itself. Deleting the element will also delete any sublist(s) attached to it.

Parameter Passing

MLISTs can be passed by reference to functions and procedures. This is similar to the way it works with ORDMAPS (see 1520.0) except that with MLISTs there is also a variation for passing sublists.

To pass a regular MLIST to a function or procedure, use the following syntax (nearly identical to that for ORDMAPs except for the "AS" clause):

call Proc( $m() ) ! passing the entire $m list by reference

Procedure Proc( $mloc() as MLIST(varstr) )

$mloc(.PUSHBACK) = "new element"

EndProcedure

The above example adds the element "new element" to the MLIST $m(). Note that the local list $mloc() is effectively just an alias for the $m() list. As with passing ORDMAP arrays and other DIMX arrays by reference, you have to initialize the array first in the calling routine.

The pre-initialization requirement does not apply to sublists though, which are automatically initalized when passing them to another routine:

call Proc( $m(.back).SUBLIST )

In the above example, the SUBLIST for the last element of the $m() list is passed to the Proc procedure (given in the previous example). Note that the procedure does not know, or care, that the caller passed a sublist rather than an MLIST base reference; they are indistinguishable from the perspective of the procedure. Also note that since the sublist gets auto-initialized if necessary, the same syntax works regardless of whether the sublist initially exists.

You can also pass a sublist of an iterator, e.g.

foreach $$i in $m()

if $$i = "something" then

call Proc($$i.sublist)

endif

next $$i

In the above example, for each element in the MLIST $m() whose value is "something", we pass the sublist to the Proc procedure, which adds a "new element" to the end of that sublist.


1521 — 08 August 2016

1521 | Language enhancement: new collection type and Ordered Multi-Map ORDMAPM supports multiple keys of the same value.
 | (no other changes for this numbered version)

Subtopics

Ordered Multi-Map ORDMAPM


Ordered Multi-Map ORDMAPM

Language enhancement: new collection type ORDMAPM is equivalent to ORDMAP except it supports multiple keys of the same value. This structure is typically known as an ordered multi-map but we went with ORDMAPM instead ORDMMAP or ORDMULMAP or ORDMULTIMAP because it seemed easier to read and type.

As with the standard ORDMAP, ORDMAPM collections declared with the DIMX statement and support the same two variations (one with a variable length string value, the other with a variable length binary/blob value; both with a variable length string key):

DIMX $mymap, ORDMAPM(varstr;varstr)

dimx $mymap, ordmapm(varstr;varx)

Note that are no promises regarding the internal order of elements with the same key, nor of which of those elements will be the one returned when retrieving an element by key. However, iterating through the entire array will return all of the elements. In addition, iterating from a specific key will also return all of the matches for that key.

For example:

dimx $MM, ORDMAPM(varstr;varstr)

...

foreach $$i in $MM(key$) ! will iterate through all of the elements

.... ! matching $key, followed by all of the

next $$i ! elements after $key


1520 — 04 August 2016

1520 | Language enhancement: Passing Ordered Maps may now be accomplished by reference to functions and procedures.
 | (no other changes for this numbered version)

Subtopics

Passing Ordered Maps


Passing Ordered Maps

Language enhancement: ordered maps may now be passed by reference to functions and procedures. Conceptually and syntatically this is very similar to passing other kinds of DIMX arrays by reference. On the calling side, you specify the array in the parameter list using an empty set of parentheses, for example...

dimx $mymap, ordmap(varstr;varstr)

...

call MyProc($mymap()) ! pass $mymap() array by reference

On the receiving side you declare the local name for the array in the parameter definition also with an empty set of parentheses, with the "as clause" specifying the ordered map type, e.g.

Procedure MyProc($m() as ordmap(varstr;varstr))

$m("foo") = "bar" ! updating m$() updates $mymap() directly

As with other DIMX array passing, the compiler does not attempt to determine if the source and destination array formats are compatible, but the runtime system enforces a degree of sanity, in this case, complaining if you attempt to pass an ordmap(varstr;varx) to an ordmap(varstr;varstr) or vice versa.


1519 — 30 July 2016

1519.0.3 | Bug fix, string stack: close a loophole created by the expandable string stack enhancement (see 1518 below) which led to a GPF fault after certain string operations on zero-length dynamic strings.
1519.0.2 | GUI refinement: non-standard dialogs, which omit the MBF_DIALOG flag and instead use the class "MIAMEDLG" along with WS_xxx flags, now support most of the standard dialog features, including the ability to center them on the desktop.
1519.0.1 | ATE enhancement: Allow ATE Custom Splash Display.

Subtopics

ATE Custom Splash Display


ATE Custom Splash Display

You can now replace the standard license/splash page with your own by creating a program ATESPLASH.LIT and placing it in the ATE directory %MIAME%\custom. As long as the file exists, and ATE was not launched with the -n option, the program will be executed instead of the standard license/banner.

Note that unlike the built-in splash display, which lingers while internal operations are proceeding, ATE will simply wait for the ATESPLASH.LIT program to exit; so you should keep the duration of the display short, ideally only one or two seconds.

Also note that the program might be executed before the full runtime environment has been established, so the program should be kept simple, with no SBX calls. Any files that you need for the display, such as an image file, should also be stored in the %MIAME%\custom subdirectory.

See sample in SOSLIB [907,50].


1518 — 27 July 2016

1518.1

Bug fix, AG_IMAGE: IMGOP_LOADDISP arguments were not getting parsed correctly when relayed to the PC. Introduced in 1512.1.

1518.0.3

Memory enhancement: Move the string expression stack out of the main partition into a separate module which now auto-expands as needed. This should eliminate the most common and yet most unpredictable cause of out-of-memory (or stack-overflow) errors, which are related to operations on strings whose size is not obvious or easily predictable.

The main partition (specified by the first and/or second values in the MEMORY statement in the miame.ini) is now used mainly for mapped variable storage, call stack, and command files. The actual RUN files are loaded separately. SYSTAT/M shows the minimum available memory in the partition since the beginning of the session, allowing you to perhaps gauge how much larger-than-necessary your partition allocation is.

Also see DIR Switch MEMREQ.

1518.0.2

MX_GETTIME Parameter UTCOFFSET can be used to retrieve the offset between UTC and local time.

1518.0.1

New TRACE option EXEC traces RUN, CHAIN, command line and XCALL AMOS statements.

Subtopics

TRACE option EXEC

MX_GETTIME Parameter UTCOFFSET


TRACE option EXEC

New TRACE option EXEC traces RUN, CHAIN, command line and XCALL AMOS statements. This is particularly useful for tracking user activity. Example trace formats:

Context | Format
RUN PROG1 (from dot prompt or command file) | <RUN:xxx> Exec(CHAIN): c:\vm\miame\dsk0\007006\prog1.run
CHAIN PROG2 (from PROG1) | <PROG1:xxx> Exec(CHAIN): c:\vm\miame\dsk0\007006\prog2.run
XCALL AMOS, "RUN PROG3" (from PROG2) | <PROG2:xxx> Exec(AMOS): Exec(AMOS): RUN PROG3
LOG DSK0:100,150 (from dot prompt or command file) | <yyyy:xxx> Exec(CMDLIN) LOG DSK0:100,150

So essentially you can search or filter for "Exec(" to easily pick up all the command lines and programs executed.

As with other TRACE options, you can set it from/in various contexts:

Context | Statement
In the MIAME.INI | TRACE=EXECUTE
From the command prompt | SET TRACE EXECUTE ON
From within a program | XCALL MIAMEX, MX_GETTRACE, trflags
From within a program | XCALL MIAMEX, MX_SETTRACE, trflags OR TROP_EXECUTE

The symbol TROP_EXECUTE is defined as &h80000000 in ashell.def.


MX_GETTIME Parameter UTCOFFSET

MX_GETTIME enhancement: the new and optional third parameter utcoffset can be passed to retrieve the offset, in seconds, between UTC and local time.

xcall MIAMEX, MX_GETTIME, secs {,usecs {,utcoffset}}

utcoffset (signed num) [out]

Returns offset in seconds between local time and UTC (Universal Coordinated Time, aka Greenwich Mean Time. Offset will be negative for timezones West of Greenwich. A value of -1 indicates an error.

Note that A-Shell versions prior to this release will ignore the utcoffset parameter, so unless you check the version, you should probably set your utcoffset value to -2 before calling the routine so that you can detect if it worked.


1517 — 20 July 2016

1517.1 | Bug fix, MX_GDICALC: the MXGDI_CALCRECT patch (1516.3) broke the MXGDI_CALCLEN sub-function.
1517.0.2 | New random number functions SRAND2 and RND2 implemented.
1517.0.1 | Compiler (edit 764) enhancement to recognize the new random generator functions RND() and SRND() in /X:2 mode; see next.

Subtopics

SRAND2 and RND2


SRAND2 and RND2

New random number generator implemented and exposed through two new functions:

SRND2(seed {,ubound, lbound {,stream}})

RND2(x)

SRND2 initializes the generator, RND2 returns the next random number per the initialization/state.

Parameters

seed (32 bit integer)

establishes the initial state of the generator. The sequence of numbers returned from RND2() will be different for each seed. A seed value of 0 results in a randomly selected seed, which is equivalent to executing the RANDOMIZE statement.

ubound, lbound (32 bit signed integer)

may be used to optionally set the range of returned values. If omitted or set equal to each other, the range of returned values will be from 0 to 1 (fractional) as with the traditional RND(). Otherwise, the returned values will be integers, uniformly distributed across the range specified by lbound and ubound, inclusive.

stream (32 bit integer)

may optionally be specified to select one of the multiple streams of values possible for a given seed. Combining 2^32 streams with 2^32 seeds increases the universe of possible sets/sequences of random values dramatically, but for most uses is probably not of much interest. Note however, that for a given seed, different streams are guaranteed never to overlap each other.

If RND2() is called without first initializing the generator with SRND2(), it will be automatically initialized as if SRND2(0) had been called, i.e. a random seed will be selected and the range of returned values will be from 0 to 1 (fractional).

The existing RANDOMIZE statement affects the new RND2() function in the same way as the traditional RND(x) function, i.e. establishes a pseudo-random seed and stream. It does not affect previously established lbound and ubound values.

The primary motivation for implementing a new random number generator is to provide vertical stability across versions and horizontal uniformity across platforms. That is, for a given set of initialization parameters, the resulting sequence of numbers returned by the new RND2() function will be the same across all A-Shell platforms, all versions going forward, and all operating system levels. This is NOT the case with the traditional RND() function, which is based on standard C library routines which have different underlying implementations in different operating systems and which may change over time. Stability and uniformity are critical for many applications of random number generators, including data encryption and test suites.

Aside from stability and uniformity, the new generator offers some additional benefits:

• The lbound,ubound feature makes it much easier and faster to generate integers in a particular range, which is probably the most common usage. It also eliminates the floating point rounding problem which allows the traditional RND(x) to sometimes return a value effectively equivalent to 1. If you are converting the result to an integer range 1-N in the usual way, i.e. INT(RND(1)*N)+1, this would lead to a result of N+1, possibly causing an error in the application.

• RND2() is much less predictable than RND(), making it superior for cryptographic uses.

• Splitting it into two functions, one to initialize and one to generate, reduces the confusion inherent in the overloaded nature of RND(x).

The new generator is based on the the PCG family of random number generators; see www.pcg-random.org for more information.

Warning: attempting to run a program containing RND2() or SRND2() in a version of A-Shell prior to 6.3.1517 will generate an unsupported function error when it hits either function.


1516 — 14 July 2016

1516.1.3 | Minor adjustment to AUI_WINDOW secondary monitor querying logic to better accommodate unexpected configurations, which may contain gaps in the combined virtual desktop space due to high-res DPI scaling on one of the monitors and/or strange alignments.
1516.3 | Bug fix, MX_GDICALC: the MXGDI_CALCRECT and MXGDI_CALCLEN operations were not properly recognizing "^M" line break indicators embedded in the text.
1516.1.2 | Bug fix: fix problem with ATE login dialog (ATELGI.SBX) trying to use ATE communication channel to host before the connection has been established.
1516.0.3 | MX_OCVT now supports 48 bit values, up from 32. This is equivalent to 12 hex characters or 16 octal characters. Note that the standard SOSLIB Fn'Dec2Hex$() function has been updated accordingly.
1516.2 | Bug fix, XTEXT: Failure of the control to recognize LF as a line terminator was leading to a situation where string buffer mode (TXFF_STRING) with RTF format was in some cases causing line breaks to be lost, sometimes along with the first token of the next line.
1516.1.1 | Bug fix: resolve problem with centering of static images nested inside a static panel when resizing dialog.
1516.0.2 | ATE refinement: when using the interactive dialog to specify the host login parameters, if the configuration is set to link the FTP login to the TELNET/SSH login, then the FTP login information will now be automatically set for the session. Previously, the first FTP operation would require a second login.
1516.0.1 | Runtime enhancement: Add support for B6 and I6 Variables .

Subtopics

B6 and I6 Variables


B6 and I6 Variables

Runtime enhancement: B6 (unsigned) and I6 (signed) are now supported in the following operations:

• Use in expressions just like any other numeric variable types.

• Conversion to other types via assignment or parameter passing, provided the receiving variable is large enough to contain the value. The only other variable type that can contain the full range of B6 or I6 values is F8. In the case of converting to string or printing, you should set SIGNIFICANCE 15 to avoid exponential notation when dealing with large values.

• Conversion from other types via assignment or parameter passing, provided the source value is within the range of the target type, which is 0 to 281474976710656 for B6, and -140737488355328 to 140737488355327 for I6. Fractional values will be truncated to leave just the integer component.

• Bitwise operators (AND, OR, NOT, XOR, EQV) supported out to 48 bits; previously was 40 bits.

• Built-in XCALLs, while having access to the new extended range of integers, have not been updated to take advantage of them. Unless the the documentation explicitly indicates otherwise, you should assume a 32 bit limit for general numeric parameters.

• Decimal, octal, and hex constants and symbol definitions now support values extending to 48 bit integer or F8 floating point; previously it was 40 bit integer or F6 floating point. You may optionally append an "L" to the end of such literal constants to make explicit that you want them to be encoded into the RUN file using the larger format, but this isn't necessary as the compiler will do it automatically as needed.


1515 — 14 June 2016

1515.0.1 | Compiler (edit 763) enhancement: preliminary support for B6 and I6 variables.
1515.0.4 | GUI refinement: MBST_xxx centering was not working with MBF2_DLGNOCAP (captionless) dialogs.
1515.0.3 | LOG.LIT 3.0(124) now explicitly reports failure to log to directory.
1515.0.2 | LOG.SBR refinement: status now returns numeric error codes on failure rather than just -1.


1514 — 14 June 2016

1514.2 | Bug fix, AUI_IMAGE: IMGOP_CAPTURE was broken by 1512.1. The bug was most noticeable in the Print Screen utility.
1514.1 | Bug fix, XTREE: in the ATE environment, updating a sortable tree from both the data and answer arrays using XTROP_REPLACE was in some cases resulting in duplicate rows or cell updates to the wrong rows. This effectively replaces earlier XTREE patches in 1421.2 and 1421.9 which failed to deal correctly with the scenario, and which actually expanded the scope of the problem to potentially affect non-ATE environments. Same patch as 6.2.1427.1.
1514.0.2 | Compiler edit 762 implements optimization for unused functions. Feature will be exposed for use in a subsequent update.
1514.0.1 | New subroutine ATELGI allow creation of a customzied ATE login.

Subtopics

ATELGI


ATELGI

xcall ATELGI, name, pw, status, pkpw, host, cfg

ATELGI.SBX provides the means for creating a customized ATE login script. If BAS:ATELGI.SBX exists and the automatic login doesn't succeed, ATE will call it instead of the internal generic login dialog to get the login credentials.

Parameters

Name | Type | I/O | Description
login | str | in/out | login name
pw | str | out | password
pkpw | str | in/out | private key passphrase
status | num | in/out | status: OK/CONNECT=1, CANCEL=0
host | str | in/out | host{:port}
cfg | str | in | name of current ATE configuration


1513 — 01 June 2016

1513.5 | Bug fix, XTREE: in the ATE environment, updating a sortable tree from both the data and answer arrays using XTROP_REPLACE was in some cases resulting in duplicate rows or cell updates to the wrong rows. This effectively replaces earlier XTREE patches in 1421.2 and 1421.9 which failed to deal correctly with the scenario, and which actually expanded the scope of the problem to potentially affect non-ATE environments. Same patch as 6.2.1427.1.
1513.4 | APEX: further refinements to zoom/pan. Same as 6.2.1427.1.
1513.3 | Bug fix, XTREE: date/time sorting (cformat D and h) was not working. This was broken in 6.1.1365 during during the unicode conversion. Same patch as 6.2.1426.8.
1513.2 | Minor internal changes for Raspberry Pi compatibility. The Pi version yet doesn't support the REGEX, FCGI, USPS, and DYNLIB/LIBXL modules.
1513.1 | Bug fix, XTREE: close loophole responsible for intermittent bogus "Editable column count" error messages. Same patch as 6.2.1426.7.
1513.0 | New XTREE Advanced Coldef Option: MaskView=<mask>. This is identical to the existing Mask=<mask> option, except that the non-numeric mask characters (relative to the current LDF) are stripped from the editable fields returned in the answer array. This is most convenient when you plan to use the data returned from the tree in numeric calculations, where the mask formatting characters may interfere with the conversion from string to number.


1512 — 13 May 2016

1512.2 | Bug fix: resolve truncation problem in standard TAB control if the label definition string (ctext) between 200 and 400 characters; Was corrupting the exitcode for the final tab. Same as 6.2.1426.6.
1512.1.1 | Source code reorganization: symbols related to AUI_IMAGE have now been separated out of ashell.def into image.def and augmented. Programs using them should now ++include ashinc:ashell.def and ++include:image.def.
1512.1.2 | IMGOP_ACQUIRE now supports optional ability to set the pagesize.
1512.0 | AUI_IMAGE enhancement: IMGOP_INFO now returns the percent black for B&W TIF images.

Subtopics

IMGOP_ACQUIRE

IMGOP_INFO


IMGOP_ACQUIRE

AUI_IMAGE enhancement: IMGOP_ACQUIRE now supports optional ability to set the pagesize.

xcall AUI, AUI_IMAGE, IMGOP_ACQUIRE, handle, status, filespec, attribs (,appname {,pages, scanflags {,pagesize}}}

Pagesize options are defined in the ashinc:ashell.def file, the most common options being:

TWSS_A4LETTER = 1

TWSS_USLETTER = 3

TWSS_USLEGAL = 4


IMGOP_INFO

The IMGOP_INFO (5) opcode now returns the percent black for B&W TIF images. The calculation eliminates some noise (individual floating bits) and also ignores an outer margin equal to 1/40th of the width and/or length, and may be useful as a way of detecting blank (or perhaps too-light or too-dark) pages during scanning.

The updated layout for the IMGINFO parameter is:

MAP1 IMGINFO ! Image info packet

MAP2 IMG'OWIDTH,F ! Original image width (pixels)

MAP2 IMG'OLENGTH,F ! Original image length (pixels)

MAP2 IMG'DWIDTH,F ! Display width (pixels)

MAP2 IMG'DLENGTH,F ! Display length (pixels)

MAP2 IMG'BPP,F ! Bits per pixel

MAP2 IMG'NA,F ! not used

MAP2 IMG'TYPE,B,2 ! type: 1=tif,2=bmp,3=jpg,4=pcx,5=tga,6=gif,7=png

MAP2 IMG'BW'BLKPCT,F ! % black pixels (B&W TIF only)


1511 — 05 May 2016

1511.3.2 | Bug fix, XTREE/ATE: the answer array wasn't getting reprocessed in XTROP_REPLACE mode when the data array was updated and row optimization was resulting in only the updated rows being transmitted to the client.
1511.3.1 | Bug fix, parameter passing: a passed floating point variable was failing to be converted properly to a received string variable if the receiving string variable length matched the past floating point variable length. For example, passing an F6 to an S6 or an F8 to an S8 was not giving the expected result.
1511.1.2 | APEX change/refinement: when previewing images (i.e. //IMAGE GDI directives), APEX now uses the same rendering logic as it does when printing to a real printer or when displaying to the screen using AUI_IMAGE. This seems to result in somewhat improved viewing aesthetics, particularly for PNG images containing fine lines (such as building plans), which previously may have appeared excessively faint when scaled down.
1511.2 | Bug fix, ATE: AutoMouse option wasn't getting initialized on connection to match the state in the previously saved settings file.
1511.1.1 | APEX refinement: clicking on the preview page in single page view to zoom and/or click-dragging to pan now works somewhat more intuitively than before. Initially it starts in auto-scroll mode, whereby the image is automatically positioned to be maximally in view. After the first single-click zoom operation, it switches to click-drag mode, which allows you to click and drag the image in any direction. If, by some combination of zooming and dragging you manage to position the image almost or entirely out of the viewing pane, just click any of the toolbar zoom or view options to reset it. Previously, the viewer used some inscrutable heuristics to decide when to switch between the click-drag mode and the auto-scroll mode, which was frustrating when working with large images highly magnified.
1511.0.1 | Enhancement to AG_MOUSE restores previous settings.
1511.0.1 | VUE 3.2(370) now uses the above technique to disable AutoMouse on the ATE client during the VUE session, then restores the prior settings on exit. Previously, this only occurred for A-Shell/Windows local mode. Note that if the ATE version is prior to 6.3.1511.0, AutoMouse will get disabled on entry into VUE, but not restored on exit.

Subtopics

AG_MOUSE


AG_MOUSE

ATE enhancement to TAB(-10,AG_MOUSE): new opcode 8 will restore the AutoMouse setting to what it was prior to the previous change via opcode 7. Syntax:

? tab(-10,AG_MOUSE);"opcode {,flags}";chr(127);

Parameters

opcode

choices are 7 to set flags or 8 to restore flags.

flags

values from the following table may be combined

Value | Action
&h0001 | Automouse disabled (default is enabled)
&h0002 | Double click sends string only (no CR)
&h0008 | Single click sends string only (no CR)
&h0010 | Singleclick sends string+CR
&h0020 | No single click auto col adjustment
&h0040 | No single click auto row adjustment
&h0080 | Doubleclick sends CR only
&h0100 | tab(-1,158) cursor reporting
&h0200 | Doubleclick sends ESC only
&h0400 | Doubleclick sends string+CR
&h0800 | Don't consider slash a token delimiter


1510 — 28 April 2016

1510.1 | Refinement to XTREE handling of optional editable dates (cformat=DE, InfDef=DO). Now, when the date-valid checkbox is unchecked, the date displayed will be blanked out. Previously, it was grayed out, but the difference wasn't enough to avoid confusion.
1510.0.4 | APEX preview control SftPrintPreview_IX86_U_20.dll updated to 2.0.7 to correct some internal inconsistencies with related controls under Windows 10. No outward behavior changes expected.
1510.0.3 | New SOSLIB routine ATEGFK.SBX retrieves a file from the PC via the ATE terminal connection.
1510.0.2 | AUI_IMAGE scanning enhancement: the IMGSF_HIDEUI (1) option in the scanflags parameter now works in single-page scanning mode. Previously single page scans (pages=1) always displayed the scanner's user interface regardless of the scanflags.
1510.0.1 | Enhancement to AUI_IMAGE allows the setting of pixel type and resolution.

Subtopics

AUI_IMAGE

ATEGFK.SBX


AUI_IMAGE

AUI_IMAGE scanning enhancement: you can now set the scanner pixel type and resolution from the application by using the second thru fourth bytes of the comp parameter:

xcall AUI, AUI_IMAGE, IMGOP_ACQUIRE, handle, status, filespec, attribs ,appname {,pages, scanflags}}

where attribs replaces the previous comp parameter and is defined as:

map1 attribs,b,4 ! compress, pixel type, resolution attributes

map1 attribsx,@attribs ! overlay to break out fields

map2 comp,b,1 ! compression options (as before)

map2 pixtype,b,1 ! pixel type: (see below)

map2 resx,b,1 ! x resolution (in multiples of 25 DPI)

map2 resy,b,1 ! y resolution (in multiples of 25 DIP)

The pixtype options are shown in the following table. The first three of these are standard for most scanners, the others are somewhat exotic and may not be supported.

Value | Definition
1 | Black and white (bi-level)
2 | Grayscale (8 bit)
3 | RGG (24 bit)
4 | Palette
5 | CMY
6 | CMYK
7 | YUV
8 | YUVK
9 | CIEXYZ

The resx and resy fields are scaled to multiples of 25 DPI (i.e. 12=300 DPI), in order to fit a reasonable range of possible resolutions in 8 bits.

For each of the pixtype, resx, and resy fields, 0 is interpreted as no change to the existing or default settings. So existing programs that pass only the old comp value will continue to work as before.

Note that for many scanners, setting the pixel type and resolution options may not have an effect unless the IMGSF_HIDEUI flag is set in the scanflags parameter. That is, displaying the scanner's user interface may override the application settings with the scanner's own previously saved settings.


ATEGFK.SBX

New SOSLIB routine ATEGFK.SBX retrieves a file from the PC via the ATE terminal connection. This is useful in situations where FTP isn't available or isn't practical. Syntax:

xcall ATEGFK, hostspec, pcspec, flags, status

parameters

hostspec (str) [in]

is the destination (native or AMOS-style)

pcspec (str) [in]

is the source (PC native)

flags (num) [in]

may contain zero or more of the following:

Value | Definition
16 | skip post-transfer verification
32 | pre-verify (skip transfer if destination matches source)
64 | ignore version 0 in pre-verification
128 | put ATEGFK.LOG in current directory rather than OPR:

status (signed num) [out]

returns status of operation:

Value | Definition
>0 | file transferred
0 | transfer not required
-1 | ATE required
-2 | source file doesn't exist
-3 | file transferred but failed to verify afterwards
-4 | transfer failure

Comments

ATEGFK.SBX may work with ATE 6.1.1357+ but will be much better with ATE 6.1.1370.0+.

See test program TSTATEGFK.BP. Both are included in [907,33] of the SOSLIB along with other ATE file-transfer related utilities.

Also see MX_ATEFILEXFR and ATEXFR.SBX


1509 — 24 April 2016

1509.3.2

Bug fix: minor refinements to close loopholes in which interactions between startup errors and error messaging/logging routines could lead to lockup of the entire system. Same as 6.2.1426.2.

1509.3.1

PDFX printing refinement: the NOABORTDLG option in the printer init files now automatically sets the //PDFX,Saver.ShowProgress dialog option to false. The theory being that if you don't want the one popup dialog, you presumably don't want the other.

1509.2.1

Bug fix, STRTOK: further fix to STRTOK (see 1426.0) to ensure that the RDELIM parameter returns the final record delimiter character when the final field is terminated by only a record delimiter rather than by field and record delimiter. Normally this would not be an issue, since programs that use STRTOK to process multiple records would have to deal with possibility of a totally empty record at the end, which will always return "" in RDELIM.

But for programs parsing just a single record with an unknown number of fields and expecting the final record delimiter to be returned in RDELIM after the final field, the prior behavior may have caused the application to report an error condition. Same as 6.2.1426.3.

1509.0.2

New MIAMEX function MX_LASTPRTFIL returns the file spec of the last file written by the PDFX printer driver.

1509.0.1

Bug fix: improve detection of native file specs that otherwise appear as if they could be AMOS-style specs.

1509.0.1

PDFX enhancement: Passing the WAIT switch to XCALL SPOOL when generating a PDF file using PDFX5+ now results in the routine waiting until the file is written to disk before returning.

Subtopics

MX_LASTPRTFIL


MX_LASTPRTFIL

New MIAMEX function MX_LASTPRTFIL (186) returns the file spec of the last file written by the PDFX printer driver.

xcall MIAMEX, MX_LASTPRTFIL, fspec

where

fspec (str) [out]

return the filespec

Currently this only works for PDFX5+, where it solves the problem of finding out the actual name of the PDF file which otherwise may be unknowable due to auto-numbering strategies in the driver, or due to the operator using the Save As dialog to rename the file. The feature may be expanded in the future to support other similar printing situations.


1508 — 05 April 2016

1508.0.9 | Bug fix / refinement, XTREE/ATE: in the case described above, the ATE-side log was registering a warning message about buffer sizes. The warning and the underlying issue have been cleaned up. Same as 6.2.1425.6.
1508.0.8 | Bug fix / refinement, XTREE/ATE: when using file mode for a multi-selection tree, previously it was transmitting the entire answer parameter. Now it transmits only the number of bytes needed for the specified rows. (Server side.) Same as 6.2.1425.6.
1508.0.7 | Bug fix / refinement, FLOCK: the memory allocation for the FLOCK cache now registers the name "FLKCACHE" in the log, which is useful when debugging memory handle use with the MALLOC TRACE. Close a memory leak whereby the cache was needlessly reallocated if FLOCK called within an SBX. Same as 6.2.1425.7.
1508.0.6 | Bug fix / refinement: XTREE was converting quote characters within the data array to apostrophes. They are now preserved. Problem occurred only in the ATE environment, and the patch applies purely to the server side; no update needed for A-Shell or ATE clients. Same as 6.2.1425.3.
1508.0.5 | Bug fix / refinement, ATE: when the transmission of a large response to the server is impeded by network congestion, the retry sequence is now more forgiving. Previously it gave up after 10 retries spaced some tens of milliseconds apart; now it keeps trying for several seconds. Same as 6.2.1425.4.
1508.0.4 | Bug fix / refinement, LINUX: minor adjustment to terminal drivers to avoid a weakness in an optimized version of some string handling library calls introduced in -el6. No problems had been observed or reported though; the adjustment just reduces uncertainty in the library implementations. Same as 1426.1.
1508.0.3 | Bug fix: fix bug in filehook system which may have allowed memory corruption under certain sequences of opens, closes, and hook operations. Same as 6.2.1426.1.
1508.0.2 | Bug fix: fix bug in function call handler in which an unmapped array in the parameter list could corrupt the call/return stack. Same as 6.2.1426.0.
1508.0.1 | Compiler (edit 761) optimization of PRIVATE_BEGIN/END logic so that the initialization is effectively "lazy", i.e. delayed until code within the module is executed. This eliminates unnecessary initializations that would otherwise occur if the ++include for the module is placed near the top of the parent program.


1507 – 22 February 2016

1507.3.2 | LICENS.LIT 2.4(133) now supports new PIC format.
1507.3.1 | Misc refinements / fixes in new license handling.
1507.0.3 | New command line switch: -noclx. When specified as the FIRST argument, it disables the search for the .clx and .cl files.
1507.0.2 | New Command Line File Option CLX .
1507.0.1 | New Command Line Switch MNTSYS.

Subtopics

Command Line Switch MNTSYS

Command Line File Option CLX


Command Line Switch MNTSYS

New command line switch allows defining a system logical device that will be searched ahead of SYS:, CMD:, and BAS:

-mntsys dev:=path

For example:

ashell -i /vm/miame.ini -mntsys asr63:=/vm/miame63/dsk0 log sys:

Assuming the specified path /vm/miame63/dsk0 existed and contained 001004, 002002, and 007006 directories, these would be search prior to the corresponding dsk0:[1,4], dsk0:[2,2] and/or dsk0:[7,6] directories.

This can be useful in situations where you want to test a new version of A-Shell without overwriting your existing DSK0: directories.


Command Line File Option CLX

New command line file option: <executable>.clx e.g. ashell.clx or ashw32.clx

Similar to the .cl file, the .clx file may be optionally placed along side the ashell executable in order to supply an alternate command line. But unlike the .cl file, which is only used if the original command line does not contain any switches, the .clx is used regardless of the original command line. This is useful in situations where you want to modify the ashell command line for all the users, without having to track down and modify all the individual user startup command or shortcut files.

Also unlike the .cl files whose contents always augment the original command line arguments, the .clx command line may either replace the original command line, or be inserted prior to the original. To get the latter effect, add a " +" to the end of the .clx command line.

For example, if the original command line is:

ashell -i /vm/miame/miame.ini log bas:

and there is an ashell.clx in the same directory as the ashell executable, containing:

-mntsys asr63:=/vm/miame63/dsk0 +

then the new effective command line will be:

ashell -mntsys asr63:=/vm/miame63/dsk0 -i /vm/miame/miame.ini log bas:

If the "+" was removed from the end of the .clx file, then the new effective command line would simply be the executable followed by the contents of the .clx file, i.e.

ashell -mntsys asr63:=/vm/miame63/dsk0


1506 – 13 February 2016

1506.2 | DYNLIB (Linux) refinement: when loading libraries, it now checks first in the bin directory before trying the system library path.
1506.1.2 | Support new LibXL license option.
1506.1.1 | Support new 6.3 PIC code format (XXXXXXX-XXXXXX-XXXXXX-XXXXXXX). The new PIC format is needed for certain extensions added in 6.3; it provides no benefits to 6.2 but is hereby supported just as a backwards capability convenience.


1503 – 20 January 2016

1503.0.3 | Bug fix, ISMBLD.LIT 2.1(142): the current logged-in device was being stored in the IDX as the IDA device when the /L:# or /B:# switch was being used. The IDA device should have been left blank except in the case an explicit device specification appears on the ISMBLD command line.
1503.0.2 | Bug fix, Windows UI: Alt+Enter—used to toggle between max and normal main window state—wasn't respecting the -mx command line switch, which removes the min/max/norm buttons from the main window, presumably to prevent the user from changing the window state.
1503.0.1 | Add new routine MX_MALLOCLIMIT to get/set MALLOCLIMIT.

Subtopics

MX_MALLOCLIMIT


MX_MALLOCLIMIT

xcall MIAMEX, MX_MALLOCLIMIT, op, limit

Parameters

op (Num) [in]

0 to get the limit and 1 to set it

buffer (B,4 or F) [out]

returns the current limit (op=0) or supplies the new limit (op=1). Units are bytes—not kilo-, mega-, or giga-bytes. Maximum practical limit is 2GB-1 (2147483647).


1502 – 10 January 2016

1502.0.3 | New ZLOCK mode 55 (ERS custom function.)
1502.0.2 | MX_SYNC refinements: Time elapsed in the sync() or fsync() call is now logged (in microsecond units) if the XDEBUG trace flag set. (This was motivated by suspicions that the sync() call is taking longer under CentOS/RHEL 6 and 7 than under CentOS/RHEL 5. Such suspicions can now be easily quantified.) Also, fsyncing now supported for ISAMA files (e.g. XCALL MIAMEX, MX_SYNC, CH {,STS}).
1502.0.1 | ATE and A-Shell/Windows enhancement: the scrollback buffer has been enlarged from 100 to 200 lines.


1501 – 06 January 2016

1501.5.2

Bug fix, MX_FIND: specifying the cdate/ctime parameters but not the udate/utime parameters was exposing a loophole which could lead to crashing A-Shell.

1501.5.1

XTREE refinement: Specifying the -$PRINT PopupMenu option was removing the print option from the popup menu, but it was not disabling the ability to print/preview using the built-in ^P command. To disable that, a new Advanced Coldef Option has been added:

Print=Disabled

Note that it doesn't really matter what follows the = sign; the only option is to disable since the default is for printing to be enabled.

1501.4

Bug fix: the .ash files were getting corrupted after repeated loading/ saving operations. Introduced in 1422.3; problem can be corrected by re-saving with this version.

1501.3

Print filter refinement: filter SBX names can now be up to ten characters; previously was six.

1501.2.3

Bug fix, XTREE: when using XTROP_REPLACE to effectively add rows, after previously deleting rows, the new rows were being added properly.

1501.2.2

ATE server-side refinement: increase the wait time on the initial handshake from 3 to 6 seconds. Some large systems with slow/congested/remote networks were occasionally hitting the timeout, causing the session to not recognize that the terminal was ATE.

1501.2.1

Bug fix, INPUT #CH: When the last line of the input file was longer than for i the input variable, if the variable was followed by the byte sequence chr(26) chr(0), the chr(26) was getting set to null. The bug has been there for years, but probably went unnoticed because the conditions for it were fairly rare.

1501.1

Bug fix, XTREE: When editing "#." and "#," fields, the number pad keys were being rejected. The regular number keys were fine.

1501.0.2

Bug fix / enhancement: Selecting bold option in the system fixed pitch font selection dialog now affects the resulting font.

1501.0.1

New SIZE.SBR Parameter FLAGS .

1501.0.1

Bug fix, SCALE: with .ISNULL(), .LINENO(), .PAGENO(): the results weren't being SCALEd, which would have been a problem when combining with the unary NOT operator, i.e. NOT .ISNULL(var). Only affect programs with an explicit SCALE value.

Subtopics

SIZE.SBR Parameter FLAGS


SIZE.SBR Parameter FLAGS

flags [out]

returns the number of lines or number of non-blank lines (for text files).

Value | Returns
0 | Number of bytes in file
1 | Number of lines in (text) file
2 | Number of non-blank lines in (text) file


1500 – 05 November 2015

1500.0.2 | Add support for third-party LibXL library. This library provides the mechanism to read and write XLS files directly, including low level features such as fonts, formats, colors, images, formulas, scroll-lock, individual row/col/cell attributes, etc. Functionality to be exposed to application developers via various API means in subsequent updates.
1500.0.1 | New XCALL DYNLIB provides general purpose ability to load and call routines in external DLLs (Windows) or shareable libraries (Linux). Initially reserved for internal use in conjunction with the new LibXL library.
1500.0.0 | A-Shell 6.3 development cycle begins 25 October 2015 with copy of A-Shell 6.1.1421. First 6.3 release published 05 November 2015.


General Information

Publisher

MicroSabio

6520 Platt Ave., #104

West Hills, CA 91307 USA

web site: www.microsabio.com

email: info@microsabio.com

voice: 818-710-8437

fax: 818-704-4882

Authors

Jack McGregor has been developing and documenting A-Shell since 1994, and his authorship continues through the date of this publication. Ty Griffin is responsible for editing, formatting, spilling and pulbishing.

Support

MicroSabio provides extraordinarily good support for A-Shell and its other software products.

The first place to go with a question is the A-Shell forum, also known as the "Bulletin Board" (BBS) and the "A-Shell Network." You can search the forum by keyword, quite possibly finding the answer(s) you need. If not, then post your question there; you have to create an account to post a question, but doing so is painless and free. (Email us if you have any problems or questions about signing up.) All of the forums are moderated by MicroSabio, which means that if another user or developer does not answer your inquiry, MicroSabio staff will.

The main MicroSabio web site contains a variety of documentation, utility, and other support pages and downloads.

If you are not getting satisfaction via these support avenues, send MicroSabio an email with your question and it will be answered promptly.

MicroSabio provides free email support for A-Shell operational issues to anyone with a current maintenance contract, and also within the first 90 days of purchasing a license. If you are running a demo copy for evaluation purposes, you can obtain free support on the BBS. If you would like a free pre-sales consultation, please contact MicroSabio. Either of these avenues is also a good way to discuss or initiate a request for more advanced support than what we can provide for free (such as help with developing subroutines, custom enhancements to A-Shell, etc.) We pride ourselves on providing a higher level of support than most other software developers with whom you may be familiar, so don't hesitate to take advantage of it.

Software History

While Under Development |  |  | At Formal Release
 | First Release |  |  | Final Release*
Version | Build | Date | Version | Build | Date
6.5 | 1600 |  |  |  |
6.3 | 1500 | November 2015 | 6.4 | 1545 | March 2017
6.1 | 1300 | Spring 2012 | 6.2 | 1421 | Autumn 2015
5.1 | 1100 | November 2007 | 6.0 | 1270 | Autumn 2011
4.9 | 850 | October 2003 | 5.0 | 997 | Autumn 2007
4.7 | 796 | February 2002 | 4.8 | 833 | June 2003
4.5 | 652 | November 1998 | 4.6 | 712 | December 1999
4.2 | 507 | August 1996 |  |  |
** | 468 | August 1995 |  |  |
4.0 | 463 | August 1995 |  |  |
3.0 | 310 | August 1993 |  |  |
2.0 | 134 | June 1991 |  |  |
1.0 | 100 | February 1990 |  |  |

* Bug fixes continue to be applied past the date of the "final" release.

** John Bown was the original developer of A-Shell, and continued through build 467. With build 468, Jack McGregor took over developer responsibilities.

Documentation History

Version | Date | Version | Date | Version | Date | Version | Date
E02 | 13 Dec 01 | C04 | 13 Jan 97 | B07 | 13 May 94 | A01 | 09 Oct 91
E01 | 20 Nov 00 | C03 | 13 Jun 96 | B06 | 16 Feb 94 | A00 | 01 Oct 90
E00 | 07 Mar 00 | C02 | 20 Feb 96 | B05 | 29 Sep 93 |  |
 |  | C01 | 25 Jul 95 | B04 | 14 Jun 93 |  |
 |  | C00 | 20 Mar 95 | B03 | 30 Mar 93 |  |
D02 | 11 Feb 99 |  |  | B02 | 13 Jan 93 |  |
D01 | 05 Oct 98 |  |  | B01 | 16 Nov 92 |  |
D00 | 20 Aug 98 |  |  | B00 | 23 Jun 92 |  |

In early 2002, a new documentation system and format was adopted, and version numbers for the documentation were abandoned.

Between 2002 and 2010, documentation was published in the CHM format, with PDF and DOC (MS Word) files available on request. Beginning in 2010, all A-Shell documentation has been online in a customized HTML format.


Documentation

Using This Document

The author of this help file says:

● Click on the little books or plus marks next to topics in the table of contents; this will expand/contract the listing of items under that heading.

● Use the Index and Search functions to quickly find topics of interest. See "Using Search" below.

● To copy the URL of the current page, copy from the address bar or click on the email icon at top of the document.

● Use "Previous" and "Next" buttons on the toolbar to go forward and backward through document. The browser's "back" button takes you to the page you last viewed, not to the previous page of the document you're viewing.

● To locate your position in a document after using search or index or links, click on "Content" and then look for the highlight. It may be necessary to scroll up/down through the table of contents.

Available Docs

All published documentation for A-Shell and related topics are listed at the MicroSabio website on the download...documents page. If that page doesn't answer your questions about what docs are available, or if you need historical docs or docs in unlisted formats, contact MicroSabio with your concerns.

Developer documentation—i.e., for more recent versions of A-Shell than have been formally released—may be available from other locations, which will be noted on the documents page.

Using Search

Along with the index, the search function provides the best way to find what you're looking for. The operators AND, OR, NOT, along with quotes, are supported and work as expected.

● Searching for quite useful, or quite and useful, will return all the pages that contain both of the words quite and useful.

● Searching for "quite useful" (with the quotes) will return the pages that contain the phrase quite useful.

● Searching for quite or useful will return all the pages that contain the word quite plus all the pages that contain the word useful.

● Searching for quite not useful, or quite and not useful, will return all the pages that contain the word quite and do not contain the word useful.

Note that many common words (this, that, the, to, for, it, them, etc.) are ignored by search unless they part of a quoted string. Also note that the case of the operators (AND, and) is not significant.

Other Tips

● To get the URL for the page you are currently viewing, copy it from the address bar of your browser or click on the little email icon Email on the right end of the tool bar.

● You can drag the border between the table of contents and the documentation body to create more room for one side or the other.

Updates

The A-Shell documentation is kept very up to date. Jack meticulously documents every change/addition/improvement to A-Shell, writes the text version of ashdevnotes, and posts it with new versions of the software. As mentioned above, you can always find the up-to-the-second release notes with the latest versions of A-Shell.

Usually within hours but no more than a day or two, Ty converts the text version of ashdevnotes into an HTML version, and posts it in the same place. All the new or changed material from ashdevnotes is incorporated immediately into the applicable manual(s) of the main A-Shell doc set, and those docs are immediately published and available.

To read the latest versions of any A-Shell documentation, simply go to the download...documents page and click on the doc that interests you.

Feedback

Just as A-Shell itself is a work in progress, so the documentation is constantly being tweaked, twiddled and improved. Ty works on the docs more or less continuously, and enthusiastically welcomes feedback of all types, particularly:

● identification of language mistakes (typos, misspellinggs, bad sentences, missing words, etc.)

● identification of "real" mistakes, namely saying something that isn't true

● suggestions for better explanations

● suggestions for index entries

If you have any comments, ideas, suggestions or other kinds of feedback, please post them in the "All Other A-Shell Topics" at the A-Shell forum or email them to us.

Subtopics

File Types


File Types

Although web-based HTML help files are recommended for most readers in most circumstances, other file formats may be applicable or needed in some situations. Sometimes, for historical reasons or by special request, the A-Shell documents may be available in other file formats. If you would like to get the documentation in a format you don’t see, it may be available on request. Continue reading for information about document formats and files types, and why you might prefer one or another.

Formats

HTML (aka "Net Help"): These help files are standard web pages, with hyperlinks, tables of contents, linked indexes and search capabilities. They reside on the MicroSabio web servers, are always up to date, and require no downloading step; pages are downloaded on demand—and very quickly. As long as you have a good internet connection, this is the preferred format for help/documentation files.

CHM (Compiled HTML, standard Windows help files): CHM files are compilations of HTML pages into a single document which includes all the features of the HTML documents. CHM files are downloaded to and accessed from your computer, and are the preferred help file format when you do not have a good internet connection. CHM files are opened using built-in components of Windows, so no additional programs are required to view them. If you are running Windows 98 or later, you have what you need in order to read CHM files. If you download them to your Windows computer and then double-click on them, they should be properly opened and displayed in the familiar help-file context. Important note: for security reasons and because they include "active content," CHM files may be blocked from displaying their contents properly by recent versions of Windows. To release the lock and have the files display properly, right click on the CHM file, select “Properties,” and then “unblock” the file.

PDF (Adobe's Portable Document Format): Various A-Shell docs have been available as PDF files in the past, and may be available on request; inquire if you are interested. Files of this type consist of exact replicas of printed pages, just as they appear in a printed manual. If you plan to print a copy of the document, this is the best type of file to download. PDF files are not hypertext documents or pure help systems, but most documents (including all the PDF files on this site) come with an interactive table of contents. This file format and the program(s) needed to read these files are the property of Adobe Systems. If your computer does not already have a copy of Adobe® Acrobat®, which you will need in order to read the files, you may download a free copy from the Adobe Acrobat download page.

PDF Printing - Important note: If you intend to print the PDF documents, be sure that your printer is configured to interpret colors as either black or white; if the printer tries to interpret colors as shades of gray, all the color printing in the document will appear as gray—i.e., light and not very readable black. A-Shell help files do not use a lot of color, but they use some for text formatting and screenshots. On pure black and white printers, configured as black and white printers, the colored material prints fine.

TXT: Text files are universally readable by all computers and all operating systems, so you can download or display them regardless of your system. They do not contain any organizational or text formatting, however, and are therefore the most difficult file type to read.

DOC: This is the native file format of Microsoft Word, and is the original source of most MicroSabio documentation files. We write the docs in Word, in other words, and translate into all the other formats with various types of conversion and authoring programs. So all of the documents are readily available in Word format, either .doc or .docx; if you want them, just ask.

Printing

HTML and CHM files are not particularly well-suited for printing. They are fine if you want to print a few pages or even a full section, but not if you want to print an entire doc/manual for reading and reference. The best format for printing is PDF. If you wish to print the docs, therefore, make sure to get a PDF version of the doc(s) you want to print. If you don’t see them here, contact MicroSabio and ask about a PDF for the doc in question.

Subtopics

CHM Files


CHM Files

CHM files have largely been superseded by HTML in the A-Shell library. CHM files were the best choice in days of limited internet access—and still are the best choice when the internet is not available. Here is some general information on CHM files.

Background Information

● Compiled HTML help ("CHM") is a proprietary format for help files developed by Microsoft. It was first used in 1997 (Win98) as a successor to the even-older WinHelp format, and is still supported through Windows XP, Vista, Win7 and Win8. Microsoft no longer creates CHM files for its own documentation and has moved on to a new format, but CHM will likely be supported for a long time.

● CHM files consist of individual web pages plus a hyperlinked table of contents. The resulting file is compressed using LZX compression, making CHM files rather efficient and relatively small.

● CHM files are created using a free tool from Microsoft called "HMTL Workshop." Many additional tools for creating CHM files, as well as other help-file formats, are on the market. They are collectively known as "help authoring" tools or systems. The help file you're reading right now was created by a combination of Microsoft Word and a help-authoring tool called "Doc to Help."

● CHM files contain "active content"--i.e., the files are executable—and therefore are frequently perceived as being security risks. Gmail, for example, blocks CHM files.

● For more information, see the Wikipedia entry for CHM files (from which some of the above facts were taken).

Problems and Solutions

● For security reasons, CHM files will normally not be displayed properly or at all when you are trying to access them from network drives or remote servers. It is possible to change your security settings to accommodate such files, but the easier solution is just to move the CHM file(s) to a local drive.

● CHM files will not work if their path or filename includes the pound (aka hash) character '#'. The hash character signifies an anchor in HTML so the CHM viewer fails to resolve the path properly and to retrieve the content. If this is your situation, move the file to a path that does not have a hash character in its name. In general, avoid using '#', '?', '&', '+', and other special characters in directory names.

● When you click on an external link inside a CHM file, the web page is opened with Internet Explorer and not with your computer's default browser. Why? Since the CHM viewer itself is a component of IE, or *is* IE operating in some special mode, the program does not issue a conventional call to the PC to use the default browser. Instead, since IE is already running and available, IE simply "tells itself" (?!!) to open the external page. There is no work-around to this "problem."

● Windows (XP/Vista/Seven) security provisions may prevent CHM files from opening. If you get a "cannot display" message in the right pane of the display window, this may be the problem. Solution: right-click on the CHM file and select Properties from the popup menu. Click on the Unblock button immediately below the Advanced button on the General page, then click Apply. Once the CHM file has been unblocked, the Unblock button disappears, and you need only do this once—i.e., not every time you open the file.

● If the ideas and suggestions mentioned above do not resolve your problems opening CHM files, you might want to do a web search for "MJ's Help Diagnostics." This is a program that checks to see if the Windows programs and components needed to display CHMs are properly and completely installed on your (Windows) computer.


Legal Notices

This documentation and the software it describes contain proprietary information belonging to MicroSabio, a California proprietorship owned entirely by Jack McGregor. The software and this related information is provided under the terms of the MicroSabio License Agreement, which contains restrictions on use and disclosure, and is protected by copyright law. This information is confidential between MicroSabio and the client, and remains the exclusive property of MicroSabio.

Due to continued product development, the information contained herein may change without notice. It is believed to be accurate and reliable, at least at the time of its writing. However, no responsibility for the accuracy, completeness or use of this information is assumed by MicroSabio. If you find any problems in the documentation, please report them to the publisher.

No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, electronic, mechanical, photocopying, recording or otherwise, without the expressed or licensed permission of MicroSabio.

Acknowledgments

Digest: Copyright © 2001-2003 Christophe Devine. Used by permission via the GNU General Public License.

Natural sort (used in BASORT, XTREE, SORTIT and elsewhere): Copyright © 2000, 2004 Martin Pool. Used by permission.

FastCGI (used in libfcgi): Copyright © 2004-2017 Free Software Foundation, Inc. Licensed under the GNU Free Documentation License, version 1.3 or later.

LibXL: Licensed from XLWare.

Trademarks

MicroSabio, A-Shell, INMEMO, INFLD and EZ-SPOOL are trademarks of Jack McGregor.

Adobe and Acrobat are registered trademarks of Adobe Systems, Inc . one mention in setup

AIX and Informix are registered trademarks of International Business Machines Corporation.

Alpha Micro, AMOS, and AlphaBASIC are registered trademarks of Alpha Micro Products, Inc.

AlphaLAN is a trademark of U.A. Systems, Inc .

Autolog is a trademark of Bob Rubendunst at Soft Machines .

BackupEDGE is a trademark of Microlite Corporation.

FacetTerm and FacetWin are registered trademarks of FacetCorp.

HP-UX is a trademark of the Hewlett-Packard Company.

Linux is a registered trademark of Linus Torvalds.

Microsoft and Windows are registered trademarks of Microsoft Corporation.

OpenSSL is a trademark of the OpenSSL Project. See OpenSSL Project License.

Red Hat is a trademark of Red Hat, Inc.

SCO is a registered trademark of Caldera Systems, Inc.

Softworks Basic is a trademark of Bob Salita.

Solaris is a registered trademark of Sun Microsystems, Inc.

UNIX is a registered trademark of The Open Group.

WS_FTP is a registered trademark of Ipswitch, Inc.

ZTERM is a trademark of Rod Hewitt at Cool.stf.

All other products, services, companies, events and publications are trademarks, registered trademarks or service marks of their respective owners.

Subtopics

MicroSabio License Agreement

OpenSSL Project License

SSLeay License

DYNCALL Library License

LIBSSH3 Library License

GnuTLS Library


MicroSabio License Agreement

This is a legal agreement between you, acting as an individual on your own behalf or as an authorized agent for your organization, and MicroSabio. By installing the software on your computer(s) or by using the software product for which this license was issued, you are agreeing to be bound by the terms of this agreement. If for any reason you do not agree to the terms of the Software License, delete all relevant files from your computer(s) and return all related physical items (disks, license forms, documentation, etc.) to the point of purchase within 30 days for a full refund.

Software License

Grant of License—Single Computer: MicroSabio grants to you the right to use the accompanying software product ("Software") on a single computer. You may not network the software or otherwise use it on more than one computer.

Grant of License—Multiple Computers: MicroSabio grants to you the right to use the software on the specific number of computers for which the software has been licensed. You may not use the software on more than the specified number of computers.

Grant of License—Multiple Users: MicroSabio grants to you the right to use the software on one or more computers but only for the specific number of users for which the software has been licensed.

Copyright. The software is owned by MicroSabio or its suppliers and is protected by United States copyright laws and international treaty provisions. Therefore, you must treat the software like any other copyrighted material (e.g., a book or musical recording) except that you may either (a) make one copy of the software solely for backup or archive purposes, or (b) transfer the software to a single hard disk provided you keep the original solely for backup or archive purposes.

Other Restrictions. You may not rent, loan, sell or otherwise transfer the software to anyone else unless (a) you permanently transfer all copies in your possession, and (b) the recipient agrees to the terms of this agreement. You may not decompile, translate, reverse engineer or disassemble the software.

Limited Warranty. MicroSabio warrants that the software will perform substantially in accordance with its accompanying written materials and published specifications, when properly installed on a properly configured computer for which it is intended, for a period of 90 days from the date of receipt.

Customer Remedies. MicroSabio's, its suppliers' and its distributors' entire liability and your exclusive remedy shall be, at MicroSabio's option, either (a) return of the price paid or (b) replacement of the software which is returned to the point of purchase with your receipt. This Limited Warranty is void if failure of the software has resulted from accident, abuse or misapplication. Any replacement software will be warranted for the remainder of the original warranty period or 30 days, whichever is longer.

Limitation of Warranty. MicroSabio, its suppliers and its distributors disclaim all other warranties, expressed or implied, including, but not limited to, any implied warranty of merchantability and fitness for a particular purpose. In no event shall MicroSabio. its suppliers or its distributors be liable for any consequential damages whatsoever arising out of the use of or inability to use this product, even if advised of the possibility of such damages.

This Agreement is governed by the laws of the State of California. If you have any questions regarding the license agreement, the limited warranty or any other matters, please write to MicroSabio at the address provided on the "Contact" page of the MicroSabio web site.


OpenSSL Project License

OpenSSL is used in A-Shell by both the ATE SSH2 transport and TCPX.SBR when the TLS or STARTTLS options are used.

Copyright © 1998-2017 The OpenSSL Project. All rights reserved.

The OpenSSL toolkit stays under a dual license, i.e. both the conditions of the OpenSSL License and the original SSLeay License apply to the toolkit. See below for the actual license texts. Actually both licenses are BSD-style Open Source licenses. In case of any license issues related to OpenSSL please contact openssl-core@openssl.org.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. All advertising materials mentioning features or use of this software must display the following acknowledgment: "This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (http://www.openssl.org/)"

4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact openssl-core@openssl.org.

5. Products derived from this software may not be called "OpenSSL" nor may "OpenSSL" appear in their names without prior written permission of the OpenSSL Project.

6. Redistributions of any form whatsoever must retain the following acknowledgment: "This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/)"

This software is provided by the openssl project "as is"' and any expressed or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the opensll project or its contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.

This product includes cryptographic software written by Eric Young (eay@cryptsoft.com). This product includes software written by Tim Hudson (tjh@cryptsoft.com).


SSLeay License

SSLeay is a component of OpenSSL and is used in A-Shell by the ATE SSH2 transport .

Copyright © 1995-2017 Eric Young (eay@cryptsoft.com). All rights reserved.

This package is an SSL implementation written by Eric Young (eay@cryptsoft.com).

The implementation was written so as to conform with Netscape's SSL.

This library is free for commercial and non-commercial use as long as the following conditions are adhered to. The following conditions apply to all code found in this distribution, be it the RC4, RSA, lhash, DES, etc., code; not just the SSL code. The SSL documentation included with this distribution is covered by the same copyright terms except that the holder is Tim Hudson (tjh@cryptsoft.com).

Copyright remains Eric Young's, and as such any Copyright notices in the code are not to be removed. If this package is used in a product, Eric Young should be given attribution as the author of the parts of the library used. This can be in the form of a textual message at program startup or in documentation (online or textual) provided with the package.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. All advertising materials mentioning features or use of this software must display the following acknowledgement: "This product includes cryptographic software written by Eric Young (eay@cryptsoft.com)." The word 'cryptographic' can be left out if the routines from the library being used are not cryptographic related.

4. If you include any Windows specific code (or a derivative thereof) from the apps directory (application code) you must include an acknowledgement: "This product includes software written by Tim Hudson (tjh@cryptsoft.com)"

This software is provided by eric young "as is'' and the author disclaims any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the author or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.

The license and distribution terms for any publically available version or derivative of this code cannot be changed—i.e., this code cannot simply be copied and put under another distribution license (including the GNU Public License).


DYNCALL Library License

The DYNCALL library provides the basis for the A-Shell subroutine "DYNLIB.SBR."

Copyright © 2007-2017: Daniel Adler and Tassilo Philipp <tphilipp AT potion-studios DOT com>

Contact: <dadler AT uni-goettingen DOT de>; <tphilipp AT potion-studios DOT com>

Web resources: http://www.dyncall.org/license

Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

The software is provided "as is" and the author disclaims all warranties with regard to this software including all implied warranties of merchantability and fitness. In no event shall the author be liable for any special, direct, indirect, or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with the use or performance of this software.


LIBSSH3 Library License

The LIBSSH3 library is used by A-Shell's "libashtls," which is used in turn by TCPX if the TCPXFLG_TLS flag is set.

Copyright © 2004-2007 Sara Golemon <sarag@libssh2.org>

Copyright © 2005, 2006 Mikhail Gusarov <dottedmag@dottedmag.net>

Copyright © 2006, 2007 The Written Word, Inc.

Copyright © 2007 Eli Fant <elifantu@mail.ru>

Copyright © 2009-2014 Daniel Stenberg

Copyright © 2008, 2009 Simon Josefsson

All rights reserved.

Web resources: https://libssh2.org/

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

• Neither the name of the copyright holder nor the names of any other contributors may be used to endorse or promote products derived from this software without specific prior written permission.

This software is provided by the copyright holders and contributors "as is" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the copyright owner or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.


GnuTLS Library

The GnuTLS library is used by A-Shell's "ashnet2," which provides SSH2 support to ATE.

Web resources: https://libssh2.org/

The library is licensed for use and distribution under the terms of the GNU Lesser General Public License version 2.1.