===========================================================================
A-Shell Development Notes Version 5.1.1130.3 (05 November 2008) 
===========================================================================
1.
---
File > Save dialog locations were not right when explicit -o specified.

2.
---
Clicking on the copyright message now dismisses it.  Also, fix ATE
problem with two copies of the Copyright message dialog being active at
once (one local, one initiated by the server), leading to a situation 
where one wouldn't go away.

3.
---
MIAMEX, MX_PWCRYPT enhancement: optional type argument allows you to 
create the original 7-bit style password encryption used by earlier
versions of ATE, in addition to the newer 8-bit style.  The two types
of encrypted passwords can be distinguished by the first byte - chr(1)
indicates type 1 (7 bit), while chr(2) indicates type 2 (8 bit). 

    xcall MIAMEX, MX_PWCRYPT, CLEARPW$, CRYPTPW$ {,TYPE}

By default it uses type 2.

===========================================================================
A-Shell Development Notes Version 5.1.1130.1 (03 November 2008) 
===========================================================================
1.
---
New AUI_CONTROL / AUI_MENU option:  The control click event can now call
an SBX by setting the MBF_CMDLIN flag and setting the CMD string to:

    SBX:sbxnam,arg1,arg2,...argN

Note that other than the "SBX:", this is essentially equivalent to the 
XFUNC syntax, but unlike XFUNC, the return value of the SBX is ignored.

Also note that the current state of A-Shell or ATE is suspended while
waiting for the SBX to return, so it is probably only a good idea to 
use this with modal functions that are reasonably limited in scope.  
(Using it to launch an entire application, which in turn may get nested
by subsequent launches is likely to burn up a lot of stack space; using
the traditional CMD = "$ASHELL ..." to launch a new instance would be
preferable in that case.  

2.
---
Minor ATE cleanup:  
- Eliminate a spurious demo licensing message during connection profile
  editing.
- Changing the top and bottom status line options on the connection 
  properties dialog now takes effect immediately.

===========================================================================
A-Shell Development Notes Version 5.1.1130.0 (02 November 2008) 
===========================================================================
1.
---
New XCALL HTTP (Windows only) to handle various kinds of HTTP requests:

    XCALL HTTP, OP, STATUS, FLAGS, URL, REQUEST, RESPONSE

Where

OP [num, in]:
   1 (XHTTPOP_REQ) = general HTTP request

STATUS [signed num, out]
    0 = ok (for simple functions)
   >0 = response code returned from HTTP server (generally means
        that operation succeeded in communicating with the
        server; whether that represents an unqualified success
        will depend on the application and the body of the response.)
   <0 = Operational errors (see ASHINC:HTTP.DEF HTTPERR_xxx)

FLAGS [num, in] sum of options flags (see ASHINC:HTTP.DEF XHTTPF_xxx)

    define XHTTPF_SSL       = &h0001    ! use SSL
    define XHTTPF_REQPOST   = &h0002    ! tells upload routine to use POST format
    define XHTTPF_REQUPLOAD = &h0004    ! uplaod files (variation of POST)
    define XHTTPF_REQHEAD   = &h0008    ! Makes the request a HEAD request
    define XHTTPF_REQXML    = &h0010    ! Makes the request a POST using text/xml content
    define XHTTPF_REQGET    = &h0020    ! Simple GET (text of HTML page)
    define XHTTPF_REQPUT    = &h0040    ! Simple PUT
    define XHTTPF_DOWNLOAD  = &h0080    ! Download a file
    define XHTTPF_FILEREQ   = &h0100    ! request arg is a filespec (or list of) not a string
    define XHTTPF_FILERESP  = &h0200    ! response arg is a filespec not a buffer
    define XHTTPF_DEBUG     = &h0400    ! outputs copy of generated request to DEBUG.REQ
    define XHTTPF_HDRBODY   = &h0800    ! parse file into headers (added individually) and body
    define XHTTPF_PARMBODY  = &h1000    ! like HDRBODY but use AddParam instead of AddHeader 
    define XHTTPF_SETFROMURL= &h2000    ! Extract path and form info from URL
    define XHTTPF_FORCEXFR  = &h4000    ! File parms are server-relative; xfer to PC

URL [str, in]
   Fully qualified URL, with optional path and/or {:port}.  Eg:
   "http://www.microsabio.net/dist/51dev/temphold/junk.zip"
   "https://www.paypal.com"
   "http://someserver.com/some/path:10080"

REQUEST$ [str, in]
   Contains content of the request, for operations that require it,
   such as uploading files, POST, etc.  Depending on XHTTPF_FILEREQ
   flag, may be a string buffer or a filespec (preferably native).
   For the XHTTPF_REQUPLOAD option, can be a list of filespecs with
   semi-colon delimiter.  Note that some options only work with
   file mode, while some may only work with string mode.  

RESPONSE$ [str, in/out]
   Body of the response.  Depending on XHTTPF_FILERESP, it is the filespec
   (preferably native) of a file, or a string buffer to return the response in.
   For errors that return STATUS<0, it may contain debugging text about the error
   rather than the actual response.   

Notes:
   If intending to routine this via ATE from a UNIX server, you should
   stick with the file mode.

===========================================================================
A-Shell Development Notes Version 5.1.1129.2 (31 October 2008) 
===========================================================================
1.
---
XTREE bug fix: date columns would only sort in one direction.  Was broken
in 5.1.1126.0 (while "improving" the support for flexible date/time 
formats).

===========================================================================
A-Shell Development Notes Version 5.1.1129.1 (30 October 2008) 
===========================================================================
1.
---
ATE enhancements:  Support new ATE profile emulation-related option:
    Top / Bottom Status
    Disable field attributes (OPTIONS=NOFLDATTR)
    No space attributes (OPTIONS=NOSPACEATTR)
    Caps lock
    Tokenize GUI text (OPTIONS=GUI_SPC_IND)

===========================================================================
A-Shell Development Notes Version 5.1.1129.0 (28 October 2008) 
===========================================================================
1.
---
Compiler/language enhancement:   ++PRAGMA FORCE_FSPEC <fspec>

Similar to FORCE_EXT <ext>, this pragma allows you to change the name
of the output file generated by the compilation.  The name you specify
may optionally contain an extension (in which case it overrides the
extension previously established by default or by prior pragmas), and
it may be in native or AMOS format.  It may also contain "%s" to 
indicate the simple name of the current source file.  (This allows
you to use a common pragma, perhaps via a ++include, which specifies
an alternate location for the run file.)  Note that in all cases the
filespec should be quoted.  Examples:

   ++PRAGMA FORCE_FSPEC "fred"   
   ++PRAGMA FORCE_FSPEC "BAS:MYNAME.RRR"
   ++PRAGMA FORCE_FSPEC "/vm/miame/run/abcdef"
   ++PRAGMA FORCE_FSPEC "NEWRUN:%s"
   
2.
---
Compiler/language enhancement:   ++PRAGMA FORCE_OLD_ISAM <boolean>

This is the equivalent of /I, causing the compiler to assume ISAM 1.x for
OPEN statements that are otherwise ambiguous.  Unlike /I, it can be turned
on and off for different sections of the source code.  Example:

   ++PRAGMA FORCE_OLD_ISAM "TRUE"

3. 
---
Compiler/language enhancement:   ++PRAGMA FORCE_IEEE <boolean>

This forces an floating point variable which does not have an explicit size
to be treated as F,8 (rather than F,6).  Also requires /X:1 or higher.

4.
---
Compiler enhancement: RETURN within a Function or Procedure is now flagged
as an error, unless there was a prior CALL <label> within that same 
function/procedure.  (It probably should be an error regardless, but
technically it is legal to nest a traditional GOSUB-type routine within
a proper function or procedure, in which case a RETURN would be needed.)
Previously, trying to execute such a dangling RETURN was likely to 
disappoint.

5.
---
AUI_MENU enhancement: new opcode MNUOP_RST (7) can be used to reset the 
main A-Shell menu back to the way it was when A-Shell was first launched:

    xcall AUI, AUI_MENU, MNUOP_RST, 0, MNU$, 0, 0, "", """, STATUS

As with other AUI_MENU commands, STATUS will be set to 0 on success.
But on failure, it will return the negative version of the OS error #,
which you can translate using MX_ERRNOMSG.

MNU$ can be "" for the standard menu (aka "MIAMEMENU") or you may select
a language specific menus by specifiying "MIAMEMENU-xxx" where xxx is the
LDF language definition (e.g. "SPA", "ITA", "POR", "FRE", "CDN" etc.)  If
there is no specific menu for the requested language, the default version
(American English) will be used.  In this case, the return status will 
be -2 (indicating that the requested menu was not found).

In the case of ATE, the menu items will be reset to the way they are at
the start of an ATE connection.

===========================================================================
A-Shell Development Notes Version 5.1.1128.2 (26 October 2008) 
===========================================================================
1.
---
ATE enhancement:  Display a connection cancel dialog while waiting for the
connection to succeed.  (Allows you to abort immediately, rather than having
to wait until the TCP request times out.)

2.
---
EVENTWAIT fix:  There was a problem with using EVW_EXCDINOUT and 
EVW_EXCDFOCUS with TAB controls.  Depending on the context, clicking on one 
of the tab panels might have failed to process the new panel, or may 
even have caused an EVENTWAIT error message.

===========================================================================
A-Shell Development Notes Version 5.1.1128.0 (23 October 2008) 
===========================================================================
1.
---
Adjust handling of saved window settings.  Previously it looked for
%MIAME%\default.ash unless a settings file was specified via the
-o switch on the command line.   In that case, if the specified filespec
started with "%USERPROFILE%\Application Data\ATE" directory, and the file
was not present, it would have looked in %MIAME%, but the File>Save 
function would have saved it to the %USERPROFILE% directory.

The new scheme:  If no -o switch is specified, the search path is:

    %APPDATA%\<appname>\<cfgname>.ash
    %APPDATA%\<appname>\default.ash
    %MIAME%\<cfgname>.ash
    %MIAME%\default.ash
    
where <appname> is "ATE" or "A-Shell" depending on the context.  
For ATE, <cfgname> is the name of the connection profile; for A-Shell
it is the name of the ini file, or "default" if the ini file is 
miame.ini.

If a -o file is specified, then it overrides the above rules, although if
the file has no directory, the search path will be %APPDATA%\<appname>
and then %MIAME%.  (This matches the prior search path when -o was used
without a fully qualified path, except that %APPDATA% works better 
(and resolves differently) under Vista.

The File>Save and File>Save As menu items have been merged into a single
File>Save... dialog, which now allows you to save the current settings to
one of the four locations/names above, and in addition contains a Save As
button for more exotic options.  It also contains a Delete button as a
convenience for deleting a saved settings file (although it does not allow
deleting the %MIAME%\default.ash file).  And, it shows the filespec of 
the settings file that the current settings were loaded from.

The objectives of the above changes were: 

a) To better support Vista, which has a different location for which
the %APPDATA% directory is not the same as %USERPROFILE%\Application Data directory;

b) To make it easier for dealers, site managers, and individual users
to manage their personal window settings without having to manually
adjust their shortcut command lines.  

The new scheme is as security-lax as the old one (allowing anyone to overwrite
the shared %MIAME%\default.ash), but the save function does always default 
to one of the %APPDATA% options (hopefully eliminating some of the accidental
overwrites). The next step will probably be to allow the shared copy to 
be password protected.

2.
---
ISAM 1.x bug fix: The prior fix in 1123.8 to accept non-standard IDX level
values (<3 or >9) as indicative of old ISAM 1.0 (i.e. 3 level) was broken
somewhere between 1123.8 and 1125.0.  The fix has been reinstated.

===========================================================================
A-Shell Development Notes Version 5.1.1127.2 (17 October 2008) 
===========================================================================
1.
---
Compiler bug fix: specifying an initial value on a MAP statement within
++PRAGMA EXTERN_BEGIN/EXTERN_END (or an ++EXTERN statement) was not 
generating any compiler error but was causing A-Shell to crash immediately
on running the program.

2.
---
AUI_CONTROL enhancement: internal icon resources can now be referenced
via the #dddd syntax (where dddd is the decimal icon number).  

3.
---
XTREE column configuration refinement: column configuration now saved 
even when tree is exited with ESC (since this is a common exit not 
necessarily considered as "cancel").  The only way to exit without 
saving is now Control-C.

4.
---
Command line refinement: selection of an internal icon using -g <name>
can now be done by number, i.e. by replacing <name> with a numeric value
1001-1999.  (These icon numbers are assigned as icons are added to the 
A-Shell executable and remain fixed thereafter.)  This is mainly of 
in ATE, where it may be more convenient than using the assigned names.
(You can optionally use the #nnnn syntax, i.e. -g #1001 or -g 1001).  

You can also specify another DLL or EXE to load the icon from, using the
-g iconame::module syntax, e.g. -g transform::ashico1

5.
---
Vista-style icons:  A first attempt at updating the ashico1.dll icon
library to Vista has been made in the form of a new ashico1v.dll 
module.  The new module has the same set of icon names, but most of 
them have been upgraded to "Vista style".  The degree of backwards
compatibility to XP and before has not yet been adequately tested.

A new version of the icon display program, ICODLG[907,27] has been
created under the name ICODLGV for testing.

6.
---
AUI_CONTROL enhancement for static icons:  A new CTYPE2 flag, 
MBF2_PIXSIZE has been defined which may be used specify display sizes 
of static icons:
     
    define MBF2_PIXSIZE = &h00000080    ! erow,ecol = size in pix

Without this flag, the EROW and ECOL parameters passed when defining a 
static icon (MBF_STATIC+MBF_ICON) have no effect, as we let Windows choose
the standard icon size based on your desktop preferences.   (On a typical
high-res monitor, this might be 32x32 pixels.)

With the flag, the EROW and ECOL parameters are interpreted as the desired
height and width in pixels.  So you might set them to, say, 48, or 64, to
display larger icons, similar to what Explorer does when it offers you
multiple display sizes. 

Eventually the concept may be extended to other controls, but for now it 
only applies to static icons.

The ICODLGV sample program in [908,27] has been enhanced to allow you to
test this feature by using a switch /## where ## is the desired size, e.g.
RUN ICODLGV/48.

===========================================================================
A-Shell Development Notes Version 5.1.1127.1 (12 October 2008) 
===========================================================================
1.
---
SCRSTS.SBX 1.3(109) (Scrolling status window handler) enhancements:

When the XTREE option is requested (see 5.1.1126.2 below for details), 
three additional optional parameters can be passed to the SCROP_INIT call

   xcall SCRSTS,SCROP_INIT,SROW,SCOL,EROW,ECOL{,PARENTID,SFLAGS,
       TITLE,CLOSECMD$,COLDEF$,XT'KBDSTR,XT'FLAGS,CTLID}

XT'KBDSTR (S,10) sets the XTR'KBDSTR member of the XTRCTL structure, so that
clicking on the status control sends the specified string.  This can be 
useful if you want to allow the user to manipulate the status window, such
as to sort, select, etc. (This probably only makes sense in conjunction with
a COLDEF that defines relevant features such as columns, popup menus, etc.)
The application would normally call the SCROP_SCROLL opcode to in response
to receiving the XT'KBDSTR.

XT'FLAGS may be used to specify additional XTREE flags, such as perhaps 
XTF_MSEL, XTF_SORT, etc.

CTLID will return the XTREE control number (XTR'CTLNO), or in the case of 
INFLD, the AUI control id.  This would only be of interest in sophisticated
situations where you wanted to bypass SCRSTS.SBX and operate on the control
directly using XTREE.SBR or INFLD.SBR.

The SCROP_SCROLL operation now supports the return of an exitcode:

    xcall SCRSTS,SCROP_SCROLL,MSG$,EXITCODE

Since the SCROP_SCROLL opcode actually puts the focus on the status control,
the EXITCODE will be that which you would have gotten from XTREE, INFLD, 
or INMEMO, depending on the environment.  This would probably be most useful
if you defined a PopupMenu, which returned interesting exitcodes.

The SOSLIB sample program REGPTR[908,29] has been updated to illustrate some
of the new capabilities of SCRSTS.

2.
---
MX_REGISTRY enhancements: 2 new operations defined for deleting keys and
values: MX_DELKEY (8) and MX_DELVALUE (9):

    xcall MIAMEX, MX_REGISTRY, REGOP_DELKEY, HKEY, SUBKEY, RIGHTS, STATUS
    xcall MIAMEX, MX_REGISTRY, REGOP_DELVALUE, HKEY, NAME, STATUS

RIGHTS [num, in] only applies when running in 64 bit Windows, in which case
it can be used to select the registry view:

    RGKEY_WOW64_32KEY   &h0200   Delete key from 32 bit registry view
    RGKEY_WOW64_64KEY   &h0100   Delete key from 64 bit registry view

HKEY [b4, in] must specify an open registry handle returned from a previous 
REGOP_OPEN operation (or may be one of the built-in hive handles, 
e.g., HKEY_CURRENT_USER, etc.)  Note that to delete a key, the 
the RGKEY_DELETE (&h00010000) access right must have been specified in 
the REGOP_OPEN call.  To delete a value, the RGKEY_SET_VALUE access right
must have been specified in the open.

SUBKEY [string, in] specifies the key to delete (within HKEY).  All values
within the key will be deleted, but if there are any nested subkeys, the 
operation will fail.  (To delete a multi-level tree, you must start from the 
lowest level and work up.)

NAME [string, in] specifies the name of a value to delete.

STATUS [f6, out] returns 0 for success, else an error code.

3.
---
Compiler refinement:  When declaring extern variables within a function
or procedure using ++pragma extern_begin (see 1125.2 below), overlay
specifications no longer are treated as errors.  This makes it much easier
to use ++include to include a set of map statements to be declared as 
external.  Note, however, that any such overlay specification is essentially
ignored by the extern declaration; as with all extern declarations, you are
merely identifying previously-defined variables, not actually defining 
anything new.

==========================================================================
A-Shell Development Notes Version 5.1.1127.0 (10 October 2008) 
===========================================================================
1.
---
New MIAMEX, MX_SHORTCUT (173) routine creates a shortcut, on the desktop
or in any other folder.

    XCALL MIAMEX, MX_SHORTCUT, TARGET$, LNKSPEC$ {, DESCR$, WORKDIR$, &
        ICON$, ICONIDX, STATUS}

TARGET$ [s,in] should be set to the object or command line that the shortcut
links to.  Any %ENV% vars will be pre-resolved, i.e. at the time the link
is created (rather than when it is clicked on).  Examples:  

    TARGET$ = """%MIAME%\bin\ashw32.exe"" -i ""%MIAMEFILE% abc"""
    TARGET$ = "http://www.microsabio.com"
    TARGET$ = """c:\company shared folders\readme.txt""" 

Note: as shown above in the first and third example, you must supply literal 
quotes as needed to enclose any path compoents of the TARGET$ command line 
that may contain embedded spaces.  (In the first example, we don't know if
%MIAME% or %MIAMEFILE% will contain embedded spaces, so we quote them to 
be safe.)

LNKSPEC$ [s,in] should be set the full filespec of the shortcut itself.  The
default extension is ".lnk"; any other extension may fail to be recognized by
the Explorer as a shortcut (or "Shell Link").  LNKSPEC$ does not require
literal quoting even if contains embedded spaces.  Example:

    LNKSPEC$ = "C:\vm\miame\test shortcut.lnk".  

Note that the filename (minus the .lnk extension and directory) will appear 
under the icon when in icon view, i.e. "test shortcut" in the above example.

To put the icon on the user's desktop, you can use the %USERPROFILE% environment
variable, e.g.:

    LNKSPEC$ = "%USERPROFILE%\Desktop\check this out.lnk"

(For the common or "all users" desktop, use "%ALLUSERSPROFILE% instead of 
%USERPROFILE%, but beware that the operation may be blocked by a variety of
security restrictions, and will require elevation under Vista.)

DESCR$ [s,in] (optional) may specify a description to be embedded within the
shortcut properties.

WORKDIR$ [s,in] (optional) may specify the starting working directory for
the process when the TARGET$ is launched.  It does not require quoting.

ICON$ [s,in] (optional) may specify a separate file from which the display
icon should be taken.  It does not require quoting.  If not specified, then
the first icon of the executable associated with the TARGET$ will be used.
(If you want to user another icon from that executable, you must specify the
module name again here.)

ICONIDX [num, in] (optional) may specify the icon index (0,1,2,...) of the
icon within the file (default is 0, the first icon).   Ignored unless 
ICON$ is not blank.

STATUS [f, out] is the return status.  0=ok.  Positive numbers are 
Windows system error codes.  (See MX_ERRNOMSG to display text).  -1
indicates no GUI support available (requires Windows or ATE).

2.
---
New TAB(-10,AG_SHORTCUT) (72) command version of MX_SHORTCUT:

    ? TAB(-10,AG_SHORTCUT);TARGET$; ","; LNKSPEC$; ","; DESCR$; ","; &
         WORKDIR$;","; ICON$;","; ICONIDX; chr(127);
    input "",STATUS

Note, however, that there is no particular need to use this form of the
command (except under non-A-Shell servers) since MIAMEX, MX_SHORTCUT will
automatically issue it as needed for ATE support.

Also note that this version does not support expansion of %ENV% variables
(another reason to use the MIAMEX, MX_SHORTCUT instead).

===========================================================================
A-Shell Development Notes Version 5.1.1126.3 (08 October 2008) 
===========================================================================
1.
---
AUI_CONTROL bug fix: close loophole leading to divide by zero when loading
an image into a zero-width control).

2.
---
SBX / Function / Procedure parameter passing fixes (both involving unusual
type conversions, such as between X and numberic variables, or between
F and S variables:

a. XPUTARG N,FVAL was not doing anything if FVAL was a floating point
variable and the caller had passed a string variable for parameter #N.
Now it converts the floating point to a string.

b. Pssing an X (unformatted) variable to a routine expecting a numeric 
parameter was attempting to do a value conversion (as if the source
variable had been a string) rather than a raw binary transfer (as 
should be the case when the source or destination is unformatted).
For example:

    MAP1 REC
        MAP2 BVAL,B,2
        MAP2 JUNK,F,6

    call AddOne(REC)
    print BVAL
    end

    Procedure AddOne(blocal as b2)
        blocal = blocal + 1
        xputarg 1,blocal
    End Procedure

In the above example, the caller is passing an unformatted variable (REC) 
to the AddOne() function, but the function is expecting to receive a B2
binary.  Previously, blocal would have received the equivalent of val(REC),
which was probably useless.  Now blocal gets set from the the first 2 bytes
of the passed REC, which is effectively the same as setting blocal = BVAL.

===========================================================================
A-Shell Development Notes Version 5.1.1126.2 (08 October 2008) 
===========================================================================
1.
---
XTREE refinement: Eliminate most of the flicker when adding text to an
existing tree using XTF_NOSEL.

2.
---
SCRSTS.SBX 1.3(108) (Scrolling status window handler) now supports an 
option to use XTREE rather than INFLD to display the scrolling status 
window.  To specfy XTREE, you must set the MBF_LISTBOX bit in the SFLAGS 
parameter when creating the scrolling status window.  An optional 
new parameter allows you to specify an XTREE column definition string:

   xcall SCRSTS,SCROP_INIT,SROW,SCOL,EROW,ECOL{,PARENTID,SFLAGS,
       TITLE,CLOSECMD$,COLDEF$} 

The rest of the SCRSTS opcode formats are unchanged. 

Although the XTREE version actually has more overhead (XTREE is a vastly
more complex control than the multi-line edit control used by INFLD), 
here are some of the reasons why you might prefer it:

a. It eliminates the 1600 char limit on the amount of text that can be
left in the window.  With XTREE, there is essentially no limit.

b. You can access many of the advanced XTREE features, such as colors, 
popup menus, columns, even multiple levels.  Note, however, that it is
up to you to supply a text string (in the SCROP_ADD or SCROP_TMADD 
calls) that is formatted to match the COLDEF specified with the SCROP_INIT.

Also note that if any of the column header fields in COLDEF$ are not blank,
then the normal column header bar will be displayed.  Otherwise it will not
(making it more like a typical scrolling status window).

The TSTSCR.BP[907,20] sample program has been updated to allow easy
experimentation with the new version.

3.
---
MX_FINDFIRST refinement: embedded %ENV% variables are now supported.

==========================================================================
A-Shell Development Notes Version 5.1.1126.1 (06 October 2008) 
============================================================================
1.
---
Compiler bug fix:  IF/ELSEIF/ENDIF (with no ELSE clause) was generating
an error but not reporting what the error was.

2.
---
INFLD bug fixes relating to forms (TYPE f) and GUI:  
- Last char of field would mysteriously reappear after deleting, replacing.
- Replacing selected chars was not re-synchronizing the form.

==========================================================================
A-Shell Development Notes Version 5.1.1126.0 (03 October 2008) 
============================================================================
1.
---
XTREE enhancement: A new mechanism allowing individual users to save/restore
their own adjustments to individual XTREE configurations.  Currently 
these adjustments include column widths, column order, sort order, and
active column.  To activate this new feature, the application must make
two changes to the code calling each XTREE:

- Use the new advanced coldef directive TreeID= to give the tree a 
unique identity, so that any user-directed modifications can be associated
with just that one tree.  (See notes below.)

- Update the XTRCTL map to define the new field XTR'USRCFG and assign it
a value from the following, based on which user-configuration options 
should be allowed to override the application-supplied values:

  Symbol (XTREE.DEF) Value Description        Other params over-ridden
  ------------------ ----- ---------------    -------------------------
  XTUCFG_COLWID         1  Column widths      Dspwid (coldef)
  XTUCFG_SRTORD         2  Sort & active col  xtr'columnactive,
                                              xtr'sortorder(),xtr'columnsort()
  XTUCFG_COLORD         4  Column order       xtr'usecolorder,xtr'colorder()
  XTUCFG_ALL          255  All        

The new XTR'USRCFG field is defined at the bottom of the current XTRCTL
map (see new XTREE.MAP, XTREE.DEF, and XTREE.SDF files in ASHINC:)...

    MAP1 XTRCTL
        ...
        MAP2 XTR'NFSELSTYLE,B,1
        MAP2 XTR'SEARCHMODE,B,1
        MAP2 XTR'USRCFG,B,1          ![127] new cfg save/restore flags
        MAP1 XTR'UNUSED2,X,16        ![127] was X,17

The TreeID may consist of an alphanumeric name, with an optional :# suffix
where # is the version of the tree (an integer value).  The idea of the 
version is so that if you modify the tree layout during an application 
update, XTREE will know not to apply previously saved configuration details 
to the new tree layout.

The TreeID (maximum 32 chars) may also contain "%p" which will be
replaced at runtime by the name of the current program.  The feature
is mainly useful for XTREEs that are implemented within SBX routines
that might be called by multiple programs, where you want to allow the
user to maintain a separate configuration in each case.  So for
example, you might use

    TreeID=SelCus-%p:1

Note, however, that currently ATE does not know the name of the current
program running on the server, so it will replace "%p" with "ATE".  If
this is a concern, you can always use XCALL GETPRG within your SBX to
retrieve the name of the main program and use it directly.

User configuration adjustments are saved in the Registry automatically,
provided that TreeID is defined.  (If XTR'USRCFG is zero, the settings
will be saved on exit, but not restored on entrance, which is one way
to force the configuration back to application-specified settings.)

Another way to deal with the possibility that the user accidentally makes
a disastrous change to the configuration (like resizing a column to zero
width, thus making it disappear entirely), is to define a PopupMenu and 
add to it the new special command $RESETCFG.  For example:

    COLDEF=COLDEF+"0~0~x~H~PopupMenu=Misc,VK_xF666;Reset Columns,$RESETCFG~~"

Selecting this option from the menu will cause the tree configuration to
be immediately reset back to the way the application had originall intended.

The configuration information is saved in the Registry as:

    HKCU\Software\MicroSabio\A-Shell\XTREE\treeid

where treeid is the value specified in the TreeID= coldef clause, but with
the version stripped. (The version is saved as a subfield rather than part
of the key, to reduce the proliferation of Registry entries.)

2.
---
Compiler / Language enhancement: New compile-time function SIZEOF(VAR)
(requires /RC or /X:2) may be used to reference the size of a previously 
mapped variable. For example:

    MAP1 VAR2,S,SIZEOF(VAR1)
or
    X = Y * SIZEOF(Z)

============================================================================
A-Shell Development Notes Version 5.1.1125.2 (27 September 2008) 
============================================================================
1.
---
Compiler/language enhancement: individual global variables can now be
declared as extern (i.e. available for reference) within a function or
procedure.  (Previously your only choice was all or nothing, via the 
++PRAGMA AUTO_EXTERN.)  There are two methods, one to declare a block
of variables, and one to declare individual variables...

To declare a block of variables as being visible within a function or 
procedure, use ++PRAGMA EXTERN_BEGIN and ++PRAGMA EXTERN_END:

    ++PRAGMA EXTERN_BEGIN
    <repeat any number of global map statements here>
    ++PRAGMA EXTERN_END

The above approach is particularly useful when you want to ++INCLUDE a
file containing a set of global map statements (perhaps a global control
record).

To declare an individual variable as being visible within a function or
procedure, use ++EXTERN in place of MAP, followed by the normal syntax
for a MAP statement.  For example:

    ++EXTERN GUIFLAGS,B,4

There are few subleties and disclaimers to consider when using either of
the above methods to declare specific global variables as being visible
within a local procedure:

- Declaring a variable with ++EXTERN or ++PRAGMA EXTERN_BEGIN does not have
any effect on the original global variable definition, althoug it does allow
the code within the procedure or function to modify the global variable at
runtime.

- The type and size may be omitted in the local extern declaration.  Also,
for arrays, the array dimensions may be omitted by just using ().  However,
if you do specify a type, size, or array dimensions, then they must match
those in the original global definition of the variable.  For example:

    !(main program)
    MAP1 GFLAGS(5),B,1
    MAP1 SFLAG$,S,1
    ...
    PROCEDURE TEST()
      ++EXTERN GFLAGS(5),B,1	! valid
      ++EXTERN GFLAGS(5),F	! invalid (types don't match)
      ++EXTERN GFLAGS(5),B,2	! invalid (sizes don't match)
      ++EXTERN GFLAGS(4),B,1	! invalid (subscripts don't match)
      ++EXTERN GFLAGS()		! valid (equivalent to GFLAGS(5),B,1)
      ++EXTERN SFLAG$           ! valid (equivalent to SFLAG$,S,1)

- The MAP level does not need to match (it doesn't even get specified for
the ++EXTERN statements).  But to the extent that there is any discrepancy
between the local and global definitions, it is the global one that actually
matters.  The local one simply allows the local routine to access the 
global variable.

2.
---
Compiler enhancement:  When the /LF switch is used (to create an LSX list
file), unreferenced variables are now listed at the end, as a convenience
for those interested in clearing dead weight out of program.  Note, 
however, that these are not errors, and in many cases, it isn't even 
desirable to remove them.  For example, it is common to group misc 
variables under a heading, e.g.

    MAP1 WORK'VARS
        MAP2 X,F
        etc.

Typically in the above case, there would probably be no explicit reference
to WORK'VARS, but you couldn't just delete it without elevating the MAP2
vars beneath it to MAP1.  So the new feature is only to be used a guide
(or ignored) as you see fit.

3.
---
Compiler/language enhancement: One or more ELSEIF clauses may now be
inserted into an extended IF/ELSEIF/ELSE/ENDIF statement (in /RC or 
/X:2 modes), e.g.:

    IF <expr1> THEN
       <statements>
    ELSEIF <expr2> THEN
       <statements>
    ELSEIF <expr3> THEN
       <statements>
    ELSE
       <statements>
    ENDIF

Previously, to accomplish the same thing you would have had to use
nested IF/ELSE/ENDIF clauses, e.g.:

    IF <expr1> THEN
       <statements>
    ELSE
       IF <expr2> THEN
          <statements>
       ELSE
          IF <expr3> then    
             <statements>
          ELSE
             <statements>
          ENDIF
       ENDIF
    ENDIF

The ELSEIF version is mainly just cleaner and easier to follow.

4.
---
Compiler bug fix: SWITCH statements now work in /RC mode, per the docs.

5.
---
COMPIL.LIT 1.1(122) enhancement: you may now use the /C:symbol syntax
to define a symbol without giving it an explicit value with the =value 
clause.  If no value is specified, the implicit value is a numeric 0.
This is most useful for defining symbols to be used in ++IFDEF or ++IFNDEF
tests, where the issue is whether the symbol is defined at all, not what
its value is.

============================================================================
A-Shell Development Notes Version 5.1.1125.1 (26 September 2008) 
============================================================================
1.
---
AUI_CONTROL bug fix: child dialogs were being positioned relative to the
parent dialog (rather than the main window) even when MBF_ALTPOS or
MBF_DLGNOCREEP was set.  (Problem introduced early in 5.1)

2.
---
PAGE.LIT 1.0(102) adds support for syntax display (PAGE /?), and also
checks and adjusts for common mistake of using PAGE <file> to display
a file, instead of PAGE TYPE <file>.  In other words, if the argument
list consists of a single filespec, and that filespec appears to be a
text file, it is treated as if the command was PAGE TYPE <file>.

============================================================================
A-Shell Development Notes Version 5.1.1125.0 (24 September 2008) 
============================================================================
1.
---
Compiler enhancement: implement conditional compilation statements:

    ++IFDEF <symbol>
    ++IFNDEF <symbol>
    ++IF <constant expr>
    ++ELSE
    ++ELIF <constant expr>
    ++ENDIF

The above statements (described individually below) are supported by
compiler modes /RC and /X:1 or higher.

++IFDEF <symbol> compiles the following statements if the specified
symbol is defined using a DEFINE statement, or is a structure defined
with DEFSTRUCT, or is defined on the compiler command line with 
a /C:symbol=value clause (see below).

++IFNDEF <symbol> is just the logical reverse of ++IFDEF <symbol>

++IF <constant expression> evaluates the specified expression and 
compiles the following statements if the expression is equivalent to
TRUE.  Constant expressions are a subset of regular Basic expressions, 
made up only of defined symbols (constants) and literals (i.e. no
variables), and a limited set of pre-defined functions and operators:

  All arithmetic operators (+,-,/,*,**,^,MOD)
  All logical operators (AND, OR, NOT)
  Comparison operators (<, >, <=, >=, ==, <>, #)
  All bitwise operators (AND, OR, NOT, NOR, XOR)
  Arithmetic functions: int(),fix(),abs(),min,max
  Scientific functions: exp(),sgn(),sqr(),sin(),cos(),tan(),atn(),fact()
  String functions: +,left(),mid(),right(),[a,b],len(),instr(),asc(),chr(),
                   str(),val(),rtrim(),edit(),strip(),pad(0
  File functions: lookup()  

Examples

  ++IF APPVER > 3
  ++IF CUSTOM$ = "MR. BIG"
  ++IF (APPVER > 3) AND (LOOKUP("xyz.bsi") # 0)

++ELIF <constant expression> is similar to ++IF <constant expression> 
except that it is used in an IF..ELIF..ELIF..ELSE..ENDIF construction.

++ELSE compiles the subsequent code only if none of the prior ++IF and
++ELIF clauses were true.

++ENDIF marks the end of the conditional construct.

Examples:

  ++IFDEF GUI
      PROGRAM MYPROG,1.0G(100)
      <source code implementing GUI verison here>
  ++ELSE
      PROGRAM MYPROG,1.0(100)
      <source code implementing text version here>
  ++ENDIF

The above illustrates one way to use conditional compilation to 
conditionally create either a GUI or text version of your RUN file, 
starting from the same source file.  Previously you could only do the
same thing with runtime conditions (which may still be a better option
in most cases), but in some cases, you may prefer to have two separate
versions of the RUN (perhaps to keep the size down, or to simplify
runtime debugging.)  Note that the symbol GUI would have had to have 
been defined somewhere prior to the compiler seeing these statements
(see below for how to define symbols on the command line).

Also note that we used two different versions of the PROGRAM statement
in the above example, so that you can easily tell which RUN version
you have by displaying it with DIR/V.

Another example:

   ++IF APPVER = 1 
     ++MESSAGE Compiling Version 1
     ++INCLUDE ver1.bsi
   ++ELIF APPVER = 2
     ++MESSAGE Compiling Version 2
     ++INCLUDE ver2.bsi
   ++ELSE
     ++ERROR No APPVER defined!
   ++ENDIF

The above illustrates the IF/ELIF/ELSE/ENDIF construct, used to select
which ++include file to use based on the defined APPVER.  See below for
an explanation of the ++MESSAGE and ++ERROR statements.

One more example:

   ++IFDEF SBX
     ++PRAGMA SBX
     <retrieve parameters, SBX setup, etc.>
   ++ENDIF

The above illustrates a simple way to allow a single source file to be 
compiled as either an SBX or a RUN file.  (The SBX symbol would need to
be defined on the compiler command line, e.g. COMPIL MYPROG/X:2/C:SBX=1)

2.
---
Compiler enhancement: ++ERROR and ++MESSAGE statements:

    ++ERROR <message>

The above statement causes the message to be displayed and is treated
as a compiler error.  This is particularly useful in conjunction with
conditional compilation, as shown in the preceding example.

    ++MESSAGE <message>

The above statement is equivalent to ++ERROR <message> except that no
error is generated.  It is useful primarily for giving you visual 
feedback during compilation that your conditions are working as expected.
See prior example.

3.
---
COMPIL.LIT 1.0(121) enhancement: New command line switch supports passing
symbol definitions into the compiler:

Syntax:
    /C:symbol=value

Example:
    COMPIL MYPROG/RC/C:APPVER=2/C:GUI="VISTA"

The above example specifies the /RC switch, plus two instances of /C
to define two symbols, APPVER=2 and GUI="VISTA".  These definitions
are treated exactly as if the following had been inserted at the top of 
the MYPROG source code:

    define APPVER=2
    define GUI="VISTA"

Note the need for quotes when defining a string symbol (per the normal
rules of the DEFINE statement).

4.
---
compil.exe 409 supports the same capabilities as described above, except
using the -c:symbol=value syntax (in place of /C:symbol=value).

5.
---
XTREE bug fixes: Radiobuttons and checkboxes where not properly centered
within their columns, but instead were about 2 pixels to the left. And
the character search was not taking into account the current item.
(Fixes contained in new SftTree_IX86_A_60.dll version 6.04).

6.
---
XTREE bug fix: Use of XTR'EXPANDLEVEL was causing item focus to be 
moved from the first selected item to its parent.  

7.
---
ATE aux printing bug fix: printer specified in Connection Properties dialog
was sometimes being ignored, using the default instfad.

============================================================================
A-Shell Development Notes Version 5.1.1124.8 (16 September 2008) 
============================================================================
1.
---
Compiler enhancement: initial values and overlays are now supported 
within DEFSTRUCT / ENDSTRUCT.

============================================================================
A-Shell Development Notes Version 5.1.1124.7 (15 September 2008) 
============================================================================
1.
---
XTREE bug fix: XTR'COLUMNSORT() was not getting updated properly (problem
exacerbated in 1122.1).

============================================================================
A-Shell Development Notes Version 5.1.1124.6 (14 September 2008) 
============================================================================
1.
---
XTREE bug fix: tab across editable cells on bottom line was in some cases
jumping to the row above.  (Problem was introduced in 1123.3)

============================================================================
A-Shell Development Notes Version 5.1.1124.5 (12 September 2008) 
============================================================================
1.
---
Clean up various minor problems related to the PREVIEW=ON and APEX=ON 
commands introduced in 1124.3 below.

2.
---
Aux printing enhancement: When attempting to print to the PROMPT: device
in a non-local Windows, the DEVICE is automatically changed to 
DEVICE=AUXLOC:PROMPT: to forward to the PC client.  (This should eliminate
a number of tech support issues that relate to attempting to print to 
the PROMPT: device on an ATSD server.)  It may also eliminate at least
one cause of a file being left in-use after a failed attempt at printing.

============================================================================
A-Shell Development Notes Version 5.1.1124.4 (11 September 2008) 
============================================================================

1.
---
PDFX Email.Type 4 refinements:

- Adjust format of log file to following:

  11-Sep-08 10:54:01 ID: XAB989, Subj: Test new Email Type 4 [OK]
     To: Jack McGregor <jack@microsabio.com>, Joaquin <joaquin@microsabio.com>
     CC: juan@microsabio.com
    BCC: microsabio@gmail.com
    SID: JACKT42:02, joaquin, PRINT

The status is always contained in brackets at the end of the top line, 
and will be either "[OK]" or "[!Err: ##]".  The top line also contains
the ID (if defined via Email.ID) and the Subject line, simplifying efforts
to verify that a particular message was successfully sent.  The machine
identification, user name, and program name have been moved to the bottom
line with the tag "SID:" (Session ID).

- Add/improve GDIPRT tracing.

2.
---
TAB(-10,AG_EVTMSG) / trace.print fix: tokenization was causing the message 
to be truncated at the first comma in some cases.

3.
---
DIR.LIT 3.0(147) fixes a problem in which the /D switch was ignoring the
/MIN:# and /MAX:# and /MINDAYS:# switches.  Also adds support for
/MAXDAYS:# (to display files recently modified).

4.
---
HOSTEX.SBR enhancement (UNIX):  An optional 3rd parameter may be specified
to receive the stdout of the specified command.  For example:

MAP1 STDOUT$,S,2048
MAP1 STS,F

    XCALL HOSTEX,"uname -a",STS,STDOUT$

This would capture the output of the "uname -a" command into the variable
STDOUT$.  

Previously, to accomplish the same thing, you would have had to pipe the
output of the command to a file, then open the file to input the result,
then delete the file.  This method is much easier and more efficient.

It also works with multi-line output, e.g.:

    XCALL HOSTEX,"ls -l",STS,STDOUT$

In this case, the individual lines of output will be delimited within 
the variable (STDOUT$) using the standard UNIX line delimiter (ASCII 10).

Note that this technique is really only reliable with "regular commands", 
especially shell commands.  If you execute an arbitrary executable, there
is no telling whether it will generate stdout in a fashion compatible with
this scheme.

Currently this does not work under Windows.

============================================================================
A-Shell Development Notes Version 5.1.1124.3 (10 September 2008) 
============================================================================
1.
---
PDFX Email.Type 4 enhancement: //PDFX,Email.Type,4 will now override
subsequent Email.Type commands, so you can effectively convert existing
program-generated files to use Email.Type,4 without modifying the programs,
by creating a prefix file, say, ASHCFG:PDFX.PFX which contains:
    //PDFX,Email.Type,4
and then adding PREFIX=ASHCFG:PDFX.PFX to any printer init files that
use DEVICE=PDFX...

2.
---
New printer init commands:
	PREVIEW = ON
	APEX = ON

PREVIEW=ON forces the SSW_PREVIEW flag (524288 or &h80000) to be set in 
the switches, provided that the SSW_NOPREVIEW flag (1048576 or &h100000)
has not already been set.  This is equivalent to passing the /PREVIEW
switch to PRINT.LIT, or setting the SSW_PREVIEW bit in the switches 
parameter to XCALL SPOOL.

APEX=ON is nearly the same as PREVIEW=ON, but is specifically for the ATE
case where you want the PREVIEW option to be ignored on the server and 
only recognized on the client.  Otherwise, activating PREVIEW on the 
server in a non-GUI environment might give you the text-mode preview,
EZTYP.

3.
---
PDFX Email.Type,4 fix:  It was not supporting ";" (semicolon) as a 
valid delimeter when multiple email addresses were included in one 
Email.To, Email.CC, or Email.BCC statement.   Now both comma and 
semicolon are allowed.

============================================================================
A-Shell Development Notes Version 5.1.1124.2 (09 September 2008) 
============================================================================
1.
---
PDFX Email.Type 4 bug fix: In some cases, the email was being sent before
the PDF writer had finished writing the file, causing it to abort with 
the error "Cannot attach PDF file - does not exist".  It now waits up to
10 seconds for the PDF file to finish being written before giving up.

2.
PDFX Email.Type 4 enhancements:  3 new commands have been implement for
use with Email.Type 4:

    //PDFX,Email.ID,idstring

This just attaches an arbitrary idstring (up to 32 chars) to the message.
Currently the only purpose of this is to identify the message in the log
(described below).  Conceptually, applications that send a lot of messages
may want to assign unique identifiers to them for tracking/followup purposes.

    //PDFX,Email.Header,hdr,hdrvalue
e.g.
    //PDFX,Email.Header,Disposition-Notification-To,jack@microsabio.com

This statement allows you to add an arbitrary header to the message. The
example given is a particularly useful one, requesting a return receipt
from the recipient when she reads the message.  Definitions of standard
headers can be found on the Internet, but keep in mind that it is up to 
the particular SMTP server and/or email client to properly interpret them.
Also note that contrary the standard //PDFX,Email.xxx,value command, this
one effectively takes two arguments - the header name and its value.  You 
can, however, enclose the last two arguments in quotes if you prefer to
maintain the single argument syntax.

    //PDFX,Email.LogFile,logfile

A-Shell will now maintain a log file of Type 4 message sent.  The default
log file is OPR:SMTP.LOG.  You can change that with the above statement.
To deactivate the log entirely, set logfile to "".

============================================================================
A-Shell Development Notes Version 5.1.1124.1 (07 September 2008) 
============================================================================
1.
---
New MX_PWCRYPT (172) function for simple password encryption (useful in GDI
files to avoid revealing SMTP password):

	xcall MIAMEX, MX_PWCRYPT, CLEARPW$, CRYPTPW$

You specify CLEARPW$, the clear text version of password, and it returns
CRYPTPW$, the encrypted version.  Note that this is a relatively simplistic
password encryption mechanism known to A-Shell and ATE, which is recognized
by the fact that the first character will be a chr(2).  If you have a need
to decrypt then, contact MicroSabio for details.  (We didn't publish the
decryption scheme because it would compromise what limited security it 
offers).

2.
---
MX_REGISTRY bug fix:  The REGOP_SET (3) opcode was always returning the
same status value as you passed it.

============================================================================
A-Shell Development Notes Version 5.1.1124.0 (04 September 2008) 
============================================================================
1.
---
XTEXT refinement: in string buffer mode, if the source and destination
parameters are the same, it no longer pre-clears the destination.  (This
was causing confusion since it effectively cleared the source before the
source got loaded into the control.)	

2.
---
Preliminary beta release of new //PDFX,Email.Type,4 
This is an improved alternate implementation of the direct-to-SMTP mode
(Email.Type,3) which didn't work that well in the version built-in to PDFX.
A significant enhancement in the new version is that it will display details
about failures to connect with the SMTP server.  (Previously there was no
log and no good way to debug such failures.)  Other enhancements:

- You may now include multiple Email.To and Email.CC directives.  (As before,
each one may contain multiple addresses, but that still limited you to the
number that would fit on one line, or about 1024 characters.)

- Email.BCC is now available.

Note that you need AshNet.DLL (as well as PDFX) to support this.

============================================================================
A-Shell Development Notes Version 5.1.1123.8 (01 September 2008) 
============================================================================
1.
---
ISAM 1.0/1.1 bug fix: New logic for detecting whether an ISAM file is in 
the old 1.0 or new 1.1 format was failing to recognize a variation of the
older format that appeared to have 255 levels.  (Was aborting with an 
invalid # of levels error.)

============================================================================
A-Shell Development Notes Version 5.1.1123.7 (26 August 2008) 
============================================================================
1.
---
Compiler bug fix (introduced in 5.1.1123.5, compil edit 405) - string
functions without an explicit default function type were being reported
as errors.

2.
---
Improvements to DEFSTRUCT:

- Upper and lower case (or mixed case) formal structure names now allowed.

- STATIC and PRIVATE instances of structures now allowed.

Note: DIMX does not support structures.

============================================================================
A-Shell Development Notes Version 5.1.1123.6 (25 August 2008) 
============================================================================
1.
---
XTREE bug fix: The patch in 1123.2 created an undesirable side effect of
making it difficult to select the last item in some lists.

============================================================================
A-Shell Development Notes Version 5.1.1123.5 (24 August 2008) 
============================================================================
1.
---
Language enhancement: defined structures.  It is now possible to assign
a type name to a set of MAP statements and then use that as if it was
a data type.  This comes in very handy when you need to have multiple 
copies of a particular data structure.  

To define a structure, use the new DEFSTRUCT and ENDSTRUCT keywords, to 
enclose a set of MAP statements (levels 2 thru 9).  For example:

    DEFSTRUCT PHONENUMBER
        MAP2 DESCR,S,20     ! e.g. Front Office, Accounts Payable, etc.
        MAP2 TYPE,S,6       ! e.g. cell, bus, home, pager
        MAP2 XNUM
            MAP3 COUNTRYCODE,S,3
            MAP3 AREA,S,3
            MAP3 NUMBER,S,10
    ENDSTRUCT

    DEFSTRUCT CUSREC
        MAP2 ID,S,6
        MAP2 NAME,S,30
        MAP2 PHNUM(5),PHONENUMBER       ! array of PHONENUMBER structures
        MAP2 BALANCE,F
    ENDSTRUCT

    MAP1 SALE,CUSREC                ! SALE is an instance of structure CUSREC
    MAP1 PROSPECT(10),CUSREC        ! PROSPECT() is an array of struct CUSREC
    MAP1 PH$,PHONENUMBER            ! PH$ is an instance of struct PHONENUMBER

    ...
    PH$ = FN'GETPHONENUM$(SALE,"cell")  ! retrieve cell # from customer SALE

    DEFINE FN'GETPHONENUM$(cus as CUSREC, type$ as S6) as PHONENUMBER
        map1 locals
            map2 i,F    
        ! locate phone number by matching type
        for i = 1 to 5
            if cus.PHNUM.TYPE(i) = type$ then
                FN'GETPHONENUM$ = cus.PHNUM(i)
            endif
        next i
    ENDIF

The above example illustrates defining two structures, PHONENUMBER and CUSREC.
The CUSREC structure even contains an array of the PHONENUMBER structures
in the PHNUM(5) field.  Then it defines an instance of the CUSREC structure
called SALE, an array of instances called PROSPECT(), and an instance of 
the PHONENUMBER structure called PH$.   

The following shows the equivalent (fully expanded) form of MAP1 SALE,CUSREC :

    MAP1 SALE
        MAP2 SALE.ID,S,6
        MAP2 SALE.NAME,S,30
        MAP2 SALE.PHNUM(5)
            MAP3 SALE.PHNUM.DESCR,S,20
            MAP3 SALE.PHNUM.TYPE,S,6
            MAP3 SALE.PHNUM.XNUM
                MAP4 SALE.PHNUM.COUNTRYCODE,S,3
                MAP4 SALE.PHNUM.AREA,S,3
                MAP4 SALE.PHNUM.NUMBER,S,10

Note the use of the period to separate the names of structure instances
from the fields in the structure. 

Jo, for example, you might read the structure from a disk file and then
print out the ID field as follows:

	READ #CH, SALE
	PRINT "Customer ID = ";SALE.ID

Defined structure names may be used similarly to the unformatted type X,
and passed to functions and procedures.  In the example above, the 
function FN'GETPHONENUM$() takes a CUSREC structure as an argument, and 
returns a PHONENUMBER structure.

(Note that because function names must contain a $ suffix if the function
returns an S or X value, and since stuctures are essentially a special
variation of the X type, any function returning a structure must have a $
on the end of the name.)

The formal parameter "cus as CUSREC" essentially creates a set of local
map statements which are identical to the ones shown above for SALE, 
except with "SALE." replaced by "cus."  Otherwise, in terms of 
parameter passing, the "cus as CUSREC" parameter is equivalent to
"cus as X246". (Previously, this is how you had to pass the structure,
and then you had to repeat the MAP2-MAP9 levesl of the structure map 
statements within the Function.  So the new method doesn't exactly add
any new capability, but it makes using structures and especially passing
them between routines much cleaner and easier.

One way to help clarify the effect of structure definitions is to compile
with the /L switch, in which case the expanded forms of the structures
will display in the LSX file.

============================================================================
A-Shell Development Notes Version 5.1.1123.4 (24 August 2008) 
============================================================================
1.
---
Bug fix: XCALL AMOS was interfering with OPTIONS=SBX_RUNDIR.  After using
XCALL AMOS,"RUN XXX", the next SBX search was looking in the directory 
where the XXX program was loaded from, rather than the directory where 
the original program was loaded from.

2.
---
Eventwait bug fix:  When multiple dialogs contained controls with the same
exitcodes associated with them, AUI_EVENTWAIT with the EVW_EXCDFOCUS and/or
EVW_EXCDINOUT flags was not always selecting the control from the current
dialog.  (The symptom was that the focus was not going to the intended
control.)

============================================================================
A-Shell Development Notes Version 5.1.1123.3 (23 August 2008) 
============================================================================
1.
---
XTREE enhancement: New advanced coldef parameters:

	RGBbgTotals=r,g,b
	RGBfgTotals=r,g,b
	RGBbgHeaders=r,g,b
	RGBfgHeaders=r,g,b

These establish the base colors for the special data lines at the top
and bottom of the tree which have been flagged as headers or totals.

Note: totals line(s) are defined via the XTF_TOTALS flag and/or 
TotalLines=# coldef parameter; headers lines are defined by the 
HeaderLines=# coldef parameter.  

Also note: "header" lines defined via HeaderLines=# should not be 
confused with the real column headers, which are not data lines at all and
which do not have adjustable colors.  The header lines we're talking about
here are just data lines that have been designated "headers" so that they
remain at the top, regardless of sorting.

============================================================================
A-Shell Development Notes Version 5.1.1123.2 (22 August 2008) 
============================================================================
1.
---
XTREE bug fix:  When the current editable cell was scrolled off the 
bottom with the vertical scroll bar, XTR'TARGETROW was being set one or
two rows too far down, making it difficult to scroll all the way to the
top (until the editable cell was moved by some other means up a few rows.)

2.
---
XTREE refinements: Reduce some instances of "dancing icons", blinking
title bars, and other kinds of unwanted display flashing when exiting
and reentering a tree during cell editing.

============================================================================
A-Shell Development Notes Version 5.1.1123.1 (21 August 2008) 
============================================================================
1.
---
GDI Printing refinement: - The //SETFONT width parameter now works more
reliably with fixed pitch fonts.  

============================================================================
A-Shell Development Notes Version 5.1.1123.0 (20 August 2008) 
============================================================================
1.
---
INPUT RAW, INPUT LINE fix:  disable the automatic removal of 
field-surrounding quotes from INPUT RAW and INPUT LINE (introduced in 
1122.9).

============================================================================
A-Shell Development Notes Version 5.1.1122.9 (19 August 2008) 
============================================================================
1.
---
INPUT CSV bug fix: The 1122.8 fix for fields like ["O" Ring] which start
with a quote that is matched mid-field was causing the next field on the
line to be ignored.

2.
---
INPUT CSV enhancement: Fields enclosed in quotes are now automatically 
de-quoted now, even when AF_CSVNOQUOTE is set.  (AF_CSVNOQUOTE is still
useful for eliminating all other quote-matching logic in files that have
non-standard quoting.)

3.
---
INPUT CSV enhancement:  AF_CSVSMARTQUOTE no longer does anything.  Its
logic is now automatic.  Previously, it only served to prevent the
improper concatenation of additional input lines in order to try to match 
up quotes that occur in the middle of a field (i.e. don't require matches).
There doesn't seem to be any value in not doing that all the time.

4.
---
INPUT bug fix: 1122.8 broke INPUT (without CSV) when dealing with quoted
fields.

============================================================================
A-Shell Development Notes Version 5.1.1122.8 (18 August 2008) 
============================================================================
1.
---
ISAM bug fix: Close loophole in new ISAM 1.1 logic for indexes with > 3 
levels in which a delete that causes updates of more than 2 levels of
IDX was leaving a block of keys stranded (invisible to ISAM 1 but not 2).

2.
---
INPUT CSV bug fix: When AF_CSVSMARTQUOTE flag set, don't choke on 
fields with formats like: "O" Ring.  (Previously it thought that a leading
quote must indicate that the field was quoted, while treating the mid-field
quote as a regular data character, thus thinking the line was unquoted. 

3.
---
(UNIX) VT220Q driver fixes to make PgUp/PgDn/Ins/Del/BS in the VA emulator
act more like AM75G.

4.
---
(Linux) EFS update: build 117.

============================================================================
A-Shell Development Notes Version 5.1.1122.7 (16 August 2008) 
============================================================================
1.
---
Windows printing bug fix:  printer names were being treated as case
sensitive, causing spurious printer-not-defined errors.

2.
---
Windows printing bug fix: printers specified via a \\machine\sharename
that were not explicitly defined locally were generating invalid printer
errors.

3.
---
ISAM enhancement: The old "classic" implementation, and the new extended
implementation (which supports variable IDX levels and block sizes) now
coexist in the same copy of ASHW32.EXE.  If the IDX uses > 3 levels or
> 512 byte IDX blocks, then the new implementation is used; otherwise the
old implementation is used.  This should reduce or eliminate most concerns
about the possibility of the new implementation introducing new bugs into
stable ISAM-based applications where the new performance features are not
enough to make up for any new risks.  Note that you can verify which 
implementation is being used for any file by using SET TRACE FOPENS ON
and SET TRACE ISAM ON.  The new implementation says "ISAMX" in the 
trace messages where the old one said "ISAM" or nothing.

============================================================================
A-Shell Development Notes Version 5.1.1122.6 (15 August 2008) 
============================================================================
1.
---
XTREE refinement: Restore operation of ALT+down arrow in combo boxes
(broken in the previous patch).

2.
---
EFS bug fix:  A serious but obscure problem in random-position stream
updating was finally resolved. As far as we can tell, the problem only
surfaced in the compiler when creating EFS to create encrypted RUN modules
directly from COMPIL.LIT, with programs using Functions and Procedures.
The result was typically a RUN module which would immediately crash with
one or more inexplicable errors (out of memory, stack overflow, seg fault,
illegal syntax code, etc.)

============================================================================
A-Shell Development Notes Version 5.1.1122.5 (14 August 2008) 
============================================================================
1.
---
XTREE refinement:  ALT+key accelerator keys now work within editable cells.
Previously, an attempt to use them would either cause the editable cell 
to exit, or (in checkbox/radiobutton cells) to be ignored.

============================================================================
A-Shell Development Notes Version 5.1.1122.4 (11 August 2008) 
============================================================================
1.
---
Filespec handling refinement:  The central AMOS-to-host filespec converter
now handles un-quoting of files.  Previously it was up to individual 
XCALLs, AG_xxx functions, etc., to do this, resulting in cases where a
quoted filespec would pass through and then fail to be recognized.

2.
---
EZSPL bug fix:  In some cases, if the file being printed was not found,
the error message would report one of EZSPL's configuration files as the
missing file.

3.
---
MX_GETFLAGS / AG_GETFLAGS / ATE refinement:  Opcode 0 (retrieve flags) was 
querying the ATE client even when it was already running locally on the 
ATE client.  Generally this was a harmless inefficiency, but could have
caused problems in nested ATE subroutines invoked via AG_XFUNC.

4.
---
AG_XFUNC refinement:  Arguments are now automatically un-quoted, allowing
arguments to be passed that contain commas (like full AMOS filespecs).

5.
---
SERCH.SBR refinement: TRACE=RW now traces SERCH read operations.

6.
---
SERCH.SBR bug fix:  SERCH was failing to find keys when operating on a file
that was opened directly in memory (i.e. by LOADing the file and then using
AUTO_MEMOPEN or the MEM: device to open it.)  The problem did not affect
memory-mapping, which is generally a better way to go anyway.

7.
---
Job status refinement:  memory-mapped READs and WRITEs now counted in the
reads/writes totals shown by JSTAT and SYSTAT/W.  (This is a good way to 
measure the improvement realized by memory-mapping, by comparing the 
average reads and writes per second with and without memory-mapping.)

8.
---
SORTIT.SBR enhancement:  F8 and F4 keys now supported.


============================================================================
A-Shell Development Notes Version 5.1.1122.3 (07 August 2008) 
============================================================================
1.
---
XTREE bug fix: combos using list substitution were sometimes matching
incorrectly due to using too few characters in selecting the matchint item.

============================================================================
A-Shell Development Notes Version 5.1.1122.2 (06 August 2008) 
============================================================================
1.
---
Windows/ATE printing refinement: Attempts to print to the AUXLOC: device
in the local/client environment now reports an invalid device and treats
it like PROMPT:  Previously it was handled like a valid but null printer,
thus leading to considerable confusion, particularly in the ATE 
environment, when the ATE printer was accidentally set to AUXLOC:

============================================================================
A-Shell Development Notes Version 5.1.1122.1 (05 August 2008) 
============================================================================
1.
---
XTREE fix: There were problems relating to use of HdrClickExit for 
application-controlled sorting (inability to click header successively
to reverse sort, failure to display the up/down arrow in the header 
based on xtr'columnsort).

2.
---
ATSYNC fix: One of the error messages relating to an ATSYNC failure had
a GPF loophole.

============================================================================
A-Shell Development Notes Version 5.1.1122.0 (04 August 2008) 
============================================================================
1.
---
Old ISAM Performance Enhancements:  For large ISAM files, you can now 
achieve much better performance by increasing the IDX block size and/or
number of index levels (from the previous fixed values of 512 and 3).
New versions of the ISMBLD and ISMDMP utilities allow access to the 
new capability.

Note that existing files remain completely compatible and will perform
exactly as before. This is also true of new files that continue to use
the old default values of 512 for the block size and 3 levels.

To take advantage of the new capabilities, you must dump the file and
build a new one with the new ISMBLD switches /B:# and /L:# (see below).

2.  ISMBLD.LIT 2.1(128) adds support for the new features via new switches:

	/B:####  (512,1024,2048,4096,8192,16384) IDX block size
	/L:#     (3-9) IDX levels
	/MI	 Memory map IDX (during load)
	/MR	 Memory map just root of IDX during load (less mem needed)
	/F	 "Fast" load (assumes no dup keys; aborts if so)
	/?	 Display switches

Note that switches were used for most of the new options, rather than
prompts, to avoid breaking compatibility with existing CMD files that 
execute ISMBLD.

COMMENTS:

IDX BLOCKS (/B:####) - Increasing the IDX block size helps by
increasing the number of keys that can be scanned per disk operation,
reducing the number of levels needed, and reducing the number of block
splits during adding, all at the cost of more bytes being transferred
to/from the disk per node accessed.  For most modern disks and
computers, the tradeoff works well, at least up to 2048.  Our
recommendation is to choose a block size 20-50 times larger than the
key size.

IDX LEVELS (/L:#) - Increasing the IDX levels helps balance the tree,
avoiding the top-heavy situation where we have to sequentially scan
many blocks at the top (root) of the tree in order to find the right
branch.  The optimum number of levels is that which results in only
one block at the root of the tree, and is related to the number and
size of keys, and inversely related to the size of the IDX blocks. 
ISMBLD (and ISMDMP) will work out the math for you and display a list
of the projected IDX blocks at each level, e.g.:

  .ISMBLD TSTNEW

  Key size: 50
  Key position: 1
  Size of data record: 64
  Number of records to allocate: 500000
    62415 index blocks will be allocated
  Empty index blocks to allocate: 62415
    Projected IDX blocks by level: 4000,20000,100000
    Warning: IDX is top heavy; consider adding levels or increasing block size.

The above example shows building a file with 500000 records each with a 50
byte key.  Using the default values (512 byte IDX block and 3 levels) the
estimated number of blocks at the top level is 4000 which is extremely 
top-heavy.  (The top level must be scanned sequentially until we find our
branch, sort of like turning the pages of the dictionary one by one to find
the right page.)  So in this case, each key lookup will take an average of
4000/2 or 2000 disk operations just for the top level, then typically one 
each for the remaining levels.

(The numbers work out nicely in this example because assuming an average
loading efficient of 60%, that gives us 5 keys per 512 byte index block, 
hence the ratio of 5X between each level of the IDX.)

Since 2000+ disk operations per key lookup is going to result in TERRIBLE
performance, let's hit Control-C here (before the IDX is built) and try
to optimize it.

To optimize this IDX, we can either increase the block size, the number of
levels, or ideally both.  Using our heuristic for the ideal block size 
of 20-50 times the key size, we could either go with 1024 or 2048; let's 
try 1024 and 6 levels:

  .ISMBLD TSTNEW/B:1024/L:6

  Key size: 50
  Key position: 1
  Size of data record: 64
  Number of records to allocate: 500000
    29415 index blocks will be allocated
  Empty index blocks to allocate: 29415
    Projected IDX blocks by level: 1,5,50,500,5000,50000

As you can see, now we have a projected IDX tree with only 1 block at the 
top or root, 5 below that, and then a 10X factor between each of the rest.
This is vastly better than the original default configuration, reducing the
average number of disk operations per key lookup from over 2000 to about 7.

If you have the time to experiment, you might want to try a block size
of 2048 (/B:2048) and 5 levels, which produces an IDX level breakdown
something like: 1,3,47,1034,22728.  It is hard to predict whether the 
decrease of one level combined with the increase in block size will be 
a net gain or loss (it will probably depend on your hardware, but probably
won't make a major difference.)

Projected vs. Actual IDX structure:  The projected number of IDX blocks
by level resulting from a particular combination of records, key size,
block size and levels is just an estimate based on an average distribution
of keys and the number of records specified.  In a production environment,
you might build the file with a small initial number of records and then
rely on the auto-expand feature to increase the file size as needed.  
Unfortunately, unlike the case with ISAM-A, the auto-expand does not 
adjust the IDX structure, it only adds blocks to it.  Thus what might be
an ideal configuration for an initial file size of, say, 10,000 records, 
might turn out to be badly top-heavy if the file grows to 500,000 records.
Thus, you may want to experiment using ISMBLD to specify the number of 
expected records (i.e. the file size you'd like to optimize the IDX for),
in order to figure out the best number of levels. (Just ^C before 
creating the actual file.)  Then you can use the appropriate /B:### and /L:#
values, and don't worry if the initial index appears to have more than 
the optimum number of levels (e.g. 1,1,3,30,3000).  Keep in mind that the
performance penalty for too many index levels is just one disk operation
per level, while the penalty for too few levels is essentially unlimited.

MEMORY MAPPING (/MI and /MR) - Under UNIX, memory mapping the IDX,
either fully (/MI) or just the first few blocks at the top of the tree
(/MR), affects only the ISMBLD loading operation.  In general memory
mapping results in a very significant performance increase, when the
total file size is small compared to the available system memory (else
it may adversely affect the cache efficiency).  /MR only maps a
handful of blocks, so there is no danger of it affecting cache
efficiency, but on the other hand, the overall benefit is smaller. If
you want to get this same effect in your application, you'll need to
use XCALL ASFLAG. 

Memory mapping does not have much benefit, if any, under Windows.

FAST LOAD (/F) - Like /MI and /MR, this also only affects the load 
operation.  It speeds the process somewhat, by eliminating the initial
key lookup operation that otherwise is performed to check whether the 
record being loaded is a duplicate.  If you know that your load file is
clean, this can shave about 20% off the load time.  But the penalty is
that if there is a duplicate key, instead of skipping the record (as in 
the normal case), the load will abort with an error.


3.  ISMBLD.LIT 2.1(129) adds a /V switch (for verbose), which displays 
progress information (percentage complete) during the build and load, and
the elapsed time for the load, plus messages confirming the /Mx and /F
switches during the load.  Additional output messages may be added later.

4.  ISMDMP.LIT 2.0(134) recognizes the new index values and reports them,
via a new switch /V (verbose), i.e.:

     .ISMDMP TEST/V

(/V also assumes TTY: output mode, saving you from having to enter "TTY:" 
in order to display the header info.)

Note that as with ISMBLD, the numbers reported are based on calculations
using the number of records allocated, key size, block size, and levels
(and does not show the actual configuration, which would require a delay
to scan the IDX blocks; that option may be added later).

ISMDMP also indicates if the IDX was built using features that require
a certain version of A-Shell, e.g.:

    .ISMDMP TEST/V

    Size of data record:     16
    Size of dir entry:       14
    Size of dir block:       1024
    Size of key:             10
    Type of key:             200 (A-Shell - requires 5.1.1122+)
    Entries per dir block:   72
    Index levels:            4
    Count by level:          1,3,198,14223
    etc.

5.  ISMBLD.SBX 2.1(129) introduced.  This is a subroutine version of 
ISMBLD.LIT which may be more convenient for building files than having
to first generate a CMD file, particularly when using the new features.
The file is actually identical to ISMBLD.LIT which is why it has the 
same version (and hash, for that matter).  It determines whether to 
act as a subroutine or LIT command based on how it is called.  In the
subroutine mode, the syntax is:

    xcall ISMBLD,opflags,status,fspec,keysiz,keypos,recsiz,reccnt &
            {,idadev,infile,maxrecs,idxblksiz,idxlvls,extrablks}

opflags [num, in]    - Operation flags (see IBF_xxx in ISMDEF.BSI)
   IBF_SECONDARY  (&h0002)       ! build secondary index
   IBF_AUTOBLKLVL (&h0004)       ! auto compute block size
   IBF_EXISTING   (&h0008)       ! process existing file (
   IBF_PROGRESS1  (&h0100)       ! progress style 1 (% at cursor location)

status  [f, out]     - Return status
    0 = success
    -1 = param error
    -2 = load terminated in mid-record
    -3 = file doesn't exist (IBF_EXISTING)
    -4 = file already exists
    -5 = load file doesn't exist
    -6 = expanded version/blocks size requires newer A
    -7 = main idx doesn't exist (for secondary load)
    30+ = erf values (during load)

fspec   [string, in] - File to create (no extension)
keysiz  [num, in]    - size of key
keypos  [num, in]    - key position
recsiz  [num, in]    - record size
reccnt  [num, in]    - # recs (initial allocation)
idadev  [string, in] - IDA device (e.g. "DSK7:") if not same as IDX
infile  [string, in] - Seq file to load from, or name of main IDX if 
                        creating a secondary IDX
maxrecs [num, in]    - Expected max # recs (for auto-determination
                         of optimum idxblksiz and idxlvls; 0 to ignore)
idxblksiz [num, in]  - IDX block size (default 512)
idxlvls   [num, in]  - IDX levels (default 3)
extrablks [num, in]  - Extra IDX blocks (if omitted, use 50%)
                           0.05 - 1.00 = % x 100, e.g. 0.5 = add 50%)

Note that although ISMBLD.SBX shares much of the same code as ISMBLD.LIT,
it offers the option of allowing ISMBLD to auto-determing appropriate 
values for the IDX block size and levels, based on the key size and
expected maximum records (while only allocating the file for the desired
initial size).  Use ISMDMP XXX /V afterwards to confirm the configuration.

6. ISMROK.SBR updated: Three new optional parameters added (IDX'LVLS, 
IDX'BLK'SIZ, and IDX'TYPE), making the new syntax:

    XCALL ISMROK,CH,IDAALC,IDAAVL{,RECSIZ,KEYSIZ,KEYPOS,DEVDRV, &
        IDXALC,IDXAVL,IDANXT,IDXNXT,IDX'LVLS,IDX'BLK'SIZ,IDX'TYPE}	

IDX'LVLS [num, out] returns the number of levels in the IDX
IDX'BLK'SIZ [num, out] return the IDX block size
IDX'TYPE [num, out] returns a bitmap field indicating the index type:

            &h0002 - secondary index
            &h0800 - A-Shell extensions; requires 5.1.1122+ 

============================================================================
A-Shell Development Notes Version 5.1.1121.9 (04 August 2008) 
============================================================================
1.
---
XTREE new feature:  New advanced column definition clauses RGBbgOdd=r,g,b
and RGBbgEven=r,g,b may be specified to set the default background color
for the odd and even rows (typically used to create a "green bar" effect
to improve readability).  Although you could have done this before using
individual row colors, the problem was that sorting would mess up the 
effect (requiring that you handle your own sorting via HdrClickExit).

Note that any other color settings pertaining to individual rows or cells
will override these.

============================================================================
A-Shell Development Notes Version 5.1.1121.8 (03 August 2008) 
============================================================================
1.
---
New SPOOL.SBR switch: SSW_APEX (4194304 or &h0400000) acts like SSW_PREVIEW
(524288 or &h80000) except that if not being processed on a local A-Shell
Windows or ATE client PC, it will be ignored so that the client can 
process it when the file is aux-printed to it.  (Otherwise the preview
processing on the server side may result in EZTYP previewing, which is the
only kind possible on the server side over telnet.

============================================================================
A-Shell Development Notes Version 5.1.1121.7 (02 August 2008) 
============================================================================
1.
---
ATE fix: A problem with aux port file transfers (via ATEAPX.SBX or 
TAB(-10,AG_SPOOLCFG) and printing) that was introduced in 1121.5 fixed.

2.
---
INFLD fix: TYPE |] (don't pad or strip blanks) was not being respected
in the case of displaying a matching item from a combo box based on a
partial match (causing a failure to match an item starting with spaces).


============================================================================
A-Shell Development Notes Version 5.1.1121.6 (31 July 2008) 
============================================================================
1.
---
ISAM-A AIX bug fix:  Attempting to GET'LOCKED a record that was locked by
another user was generating a Basic error 23 (protection violation) rather
than just returning the ISAM_NA (-2) status.  (Problem only affected AIX
due to a difference in the way it handles such lock conflicts internally.)

2.
---
ATE MX_GDICALC fix:  Opening a printer context for the PROMPT: printer was
using the default printer rather than prompting.   (Note that this fix 
also requires that the server side be updated, lest the delay caused by 
prompting may cause the command to time out on the server side.)

3.
---
MX_GDICALC fix:  Using a rectangle too small to hold any characters was
causing an infinite loop.

4.
---
ASHLPD-related enhancement: When A-Shell looks for an image or xtext file,
it now checks the ASHLPD: directory if it fails to find it in the specified
location, or in the ATECACHE or ATEPERMCACHE directories.  This is mainly
useful for ASHLPD.  

5.
---
ASHLPR.SBX 1.4(117) now handles GDI files with embedded //XTEXT commands.
(Separately transfers the XTEXT file to ASHLPD so that it can be processed
locally, same as it does with //IMAGE commands.)

============================================================================
A-Shell Development Notes Version 5.1.1121.5 (29 July 2008) 
============================================================================
1.
---
ATE-ATSD fix: Close loophole by which file transfers using the aux port
protocol might be confused by ATE with something to be printed or previewed.

2.
---
APEX bug fix:  A failed search operation was crashing with a GPF if the
associated messages had not yet been loaded (by some other printing 
operation.)

3.
---
MX_GDICALC enhancement: The font width parameter is now supported.

============================================================================
A-Shell Development Notes Version 5.1.1121.1 (25 July 2008) 
============================================================================
1.
---
ATE-ATSD printing fix: Some tracing and printing messages were ending up 
on the ATSD console rather than on the ATE client, causing the job to 
appear to hang.  Tracing messages are now forwarded from the server to 
the ATE client for display in ATE's debug message window.  

============================================================================
A-Shell Development Notes Version 5.1.1121.0 (23 July 2008) 
============================================================================
1.
---
New ISAM-A feature: "Pure" indexes. These are indexes (IDX files) that 
have no accompanying DAT file.  To create them, set the record size to 0.
These could be useful for situations where you want to create a synthetic
index that wouldn't otherwise be legal, or perhaps an index to some other
kind of data.  

Note that to maintain such indexes, you use the normal ISAM-A statements,
just as if there was data attached.  (The "record" in this case, is just
a copy of the key.)   Prior to using CREATE'RECORD, you must set the 
record number variable associated with the file to the appropriate value
that you want associated with the key.  After looking up the key, for
example, using FIND, the record number variable will be returned to you
(so that you could then access the record by whatever means).

============================================================================
A-Shell Development Notes Version 5.1.1120.2 (23 July 2008) 
============================================================================
1.
---
EZTYP/APEX confusion fix: Previously, PRINT FILE/PREVIEW would have launched
EZTYP if not running under a local Windows GUI. This was disappointing 
those who were running ATE and expecting the operation to result in the 
file being previewed in APEX.  Now, PRINT FILE/PREVIEW will just proceed
with the print operation (which hopefully involves DEVICE=AUXLOC:) and just
passes the PREVIEW flag along to the printer.  Thus, from an ATE connection
to either UNIX or ATSD (Windows), PRINT LOCAL=FILE/PREVIEW will display
FILE in APEX on the ATE workstation, provided that the LOCAL printer init
contains DEVICE=AUXLOC: and that the ATE Preview Preferences are not set
to NEVER.  If you want to force the use of EZTYP, use EZTYP.LIT, or an
EZ-SPOOL configuration file.

============================================================================
A-Shell Development Notes Version 5.1.1120.1 (21 July 2008) 
============================================================================
1.
---
XTREE bug fix: Image cells were being lost when using XTROP_RESELECT in
non-editable trees.

2.
---
APEX bug fix: The %# (total pages) macro was computed the total page 
count incorrectly for GDI reports.  (It was counting each GDI command as
a line when figuring lines per page.)

============================================================================
A-Shell Development Notes Version 5.1.1120.0 (19 July 2008) 
============================================================================
1.
---
XTREE enhancement:  New selection style options (xtr'selectarea), 
defined in XTREE.DEF:

    define XTRSEL_STY_ALL_GRD    = &h0050 ! [109] STY_ALL + gradiant
    define XTRSEL_STY_CELLS_GRD  = &h0060 ! [109] STY_ALL + gradiant
    define XTRSEL_STY_CELL1_GRD  = &h0070 ! [109] STY_CELL1T + gradiant

These are equivalent to the existing options (without the _GRD suffix)
except that if the version of Windows supports the GDI+ subsystem, the
selection bar is turned into a gradiant with a dotted outline. (Eye candy)

2.
---
XTREE enhancement: New character search mode options, set via a new
field in the XTRCTL structure (XTR'SEARCHMODE):

    map1 XTRCTL       ! extended XTREE parameters	
        ...
        map2 XTR'TARGETCOL,B,1
        map2 XTR'NFSELSTYLE,B,1
        map2 XTR'SEARCHMODE,B,1
        map2 XTR'UNUSED,X,17

The options are defined as follows (in ASHINC:XTREE.DEF)

    define XTRSRCH_TOP_ALL  = 0     ! (dflt) all chars, items, from top
    define XTRSRCH_TOP_ONE  = 1     ! one char, all items, from top
    define XTRSRCH_NONE     = 2     ! no search
    define XTRSRCH_TOP_ALLX = 3     ! like TOP_ALL but skip collapsed deps
    define XTRSRCH_TOP_ONEX = 4     ! like TOP_ONE but "  "
    define XTRSRCH_NXT_ONE  = 5     ! like TOP_ONE but start from cur itm, wrap
    define XTRSRCH_NXT_ONEX = 6     ! like TOP_ONEX but "  "   "
    define XTRSRCH_NXT_ALL  = 7     ! like TOP_ALL but start from cur item
    define XTRSRCH_NXT_ALLX = 8     ! like NXT_ALL but skip collapsed deps

Previously, mode 0 (XTRSRCH_TOP_ALL) was always set. The options can be
understood as follows:

"_TOP" vs "_NXT": Indicates whether the search operation always restarts
from the top, or from the current item. In the latter case, it wraps from
the bottom back to the top.

"_ALL" vs "_ONE": Indicates whether the search is based on all the characters
in the cells of the current column, or just the one first character.  In the 
_ALL case, characters typed within 1 second of the previous character are
added to the search key; after 1 second, the key is reset.  So for example
if you type "AB" within 1 second of each other, it will search for items 
starting with the combination "AB" (not case sensitive).  If more than 1
second passed between the "A" and the "B", it restarts the search looking 
for items beginning with "B".  The "_ONE" option effectively sets the 
timer to zero, so that each character typed restarts the search.

"X" (_ALLX, _ONEX): The "X" on the end indicates that collapsed child items
are skipped.  Otherwise, the search considers all items, and if it matches
a collapsed child item, that child and all its siblings and parents are 
expanded.

3.
---
Calendar control bugfix:  Querying the control to get the date showing
(via CTLOP_QRYCB) was returning 0 unless the control had been updated by
some external event (mouse click, system clock changeover, gaining the
focus, etc.)

4.
---
EFS (Encrypted File System for A-Shell/Linux) updated to build 112.

5.
---
MX_EXPFIL bug fix: It was returning positive values for system errors, 
rather than negative.

============================================================================
A-Shell Development Notes Version 5.1.1119.2 (09 July 2008) 
============================================================================
1.
---
XTREE refinement: The determination of whether a "\" marks the beginning
of hidden text has been improved for array-mode trees.  Previously, unless
one of the columns specified the cformat code "\", all backslash characters
were considered as the start of hidden text (from there to the end of the
row).  This was taking people by surprise, especially when the backslash
occurred in an editable column (like in a filespec).  The new rule is that
a backslash will be treated as a literal character if ANY of the following
is true:

- The cformat code "\" is present for any column (as before).
- The backslash occurs prior to the last physical column in the array data
  (without regard to the order in which the logical columns are defined).
- The last physical column is editable.

2.
---
Startup command line parsing bugfix: A-Shell scans the startup command line
for "\n" in order to allow multi-line commands (virtual command files) to
be passed on the ashell (or ashw32) command line.  It has always had a 
test to determine whether any "\n" was part of a filespec (e.g. c:\new.txt)
but the test failed to recognize the case where the filespec was preceded
by a "=" with no space.  Thus:

   ... ztxfer xxx=c:\temp\new.txt

would have been intepreted as:

   ... ztxfer xxx=c:\temp  <newline>
   ew.txt

3.
---
Rogue filespec bugfix: Filespecs longer than 256 chars were in some cases
corrupting the A-Shell stack (usually causing A-Shell to crash.)

============================================================================
A-Shell Development Notes Version 5.1.1119.1 (07 July 2008) 
============================================================================
1.
---
MX_COPYFILE bug fix: attempting to copy a random file via its file channel
was sometimes causing a program abort.

2.
---
INPUT CSV bug fix: hitting EOF while trying to match up a double-quote
was causing an infinite loop (problem introduced in 1119.0).  A-Shell
now displays a warning message when this situation arises, since it 
almost certainly indicates a problem with the parsing of the data.

============================================================================
A-Shell Development Notes Version 5.1.1119.0 (06 July 2008) 
============================================================================
1.
---
INPUT CSV enhancement: two new variations may be enabled via new ASFLAG.SBR
flags:

AF_CSVNOQUOTE  2048  (&h800)  Disables all special handling of 
double-quote characters (ASCII 34, or "), treating them as ordinary data
characters.   

AF_CSVSMARTQUOTE 4096 (&h1000) Enables "smart" handling of double-quote
characters.  A-Shell looks at the context of the line to guess whether
a double-quote character is being used to enclose a field (that may
contain special characters, including line breaks), or it is simply 
an ordinary data character.

2.
---
INPUT CSV fix: Fields that started with a double-quote were being effectively
terminated at the next double-quote, so that a field like:

    "There are 12" in a foot"

was being reduced to "There are 12".

3.
---
INPUT CSV fix: Double-Double-quotes were not being intepreted as a single
double-quote data character unless the field was quoted.  Thus the
following line:

    There are 12"" in a foot

would have remained unfiltered, while this line:

    "There are 12"" in a foot"

would have ended up with 12" instead of 12"".

============================================================================
A-Shell Development Notes Version 5.1.1118.6 (03 July 2008) 
============================================================================
1.
---
GDI printing fix:  The special symbol "%#" (which is supposed to be 
replaced by the total number of pages in the printout) wasn't working.

2.
---
APEX now supports the DELETE switch in SPOOL.SBR, as well as the DELETE
command in the printer init files, to delete the file after previewing.

3.
---
STATIC & PRIVATE variable initialization bug fix:  These variables were
getting cleared but not properly re-initialized when re-running a RUN or
SBX file from memory (i.e. either due to the automatic cache or the 
LOAD command.)

============================================================================
A-Shell Development Notes Version 5.1.1118.5 (02 July 2008) 
============================================================================
1.
---
Remove screen warning message "Class Already Exists" when calling the
InitCommonControlsEx() function to initialize the Windows Common Dialog
Control classes.  Apparently the condition occurs in some versions of 
windows, but is harmless and not worth bothering the user about.  

============================================================================
A-Shell Development Notes Version 5.1.1118.4 (02 July 2008) 
============================================================================
1.
---
AUTLOG.SBR fix: back out change to default buffer size made in 5.1.1117.0
(was causing some kind of interference with the Autolog interface).  Note
that you can still increase the buffer size (i.e. maximum packet size)
by passing the larger packet variable size in the initial AUTLOG call.

As a byproduct of the debugging, there are now a number of traces that will
appear within AUTLOG.SBR if you set the XDEBUG trace flag.

============================================================================
A-Shell Development Notes Version 5.1.1118.3 (29 June 2008) 
============================================================================
1.
---
APEX / W2K compatibility fix:  the buttons on the APEX toolbar to the right 
of the "Close" button were not appearing at all in W2K.

============================================================================
A-Shell Development Notes Version 5.1.1118.2 (27 June 2008) 
============================================================================
1.
---
Windows printing bug fix: PITCH=AUTO was not adding the LMARGIN value to 
the line length to compute the required font, thus causing lines to be
truncated by the amount of the margin.

2.
---
APEX bug fix:  A-Shell was hanging in the case where the printfile ended
in an unterminated line that contained a FF followed by some other garbage.
============================================================================
A-Shell Development Notes Version 5.1.1118.0 (27 June 2008) 
============================================================================
1.
---
CentOS arithmetic bug fix: Calculations involving B4 variables which had
been assigned negative values were not working properly.  Although 
B variables are unsigned, it is legal to assign them negative values, and
for the most part, when performing calculations involving other B variables,
the results are actually consistent.  For example:

    MAP1 BTOT,B,4
    MAP1 BVAL,B,4
    BTOT = 100
    BVAL = -5
    BTOT = BTOT - BVAL

The resulting BTOT should be 105 (100 - -5).  But under CentOS, apparently
due to a change in the C compiler behavior, BVAL was getting "pinned" to
the minimum signed integer of -(2^31), causing BTOT to be set to a very
large number.

This kind of arithmetic operation is dangerous in the best of cases (any
assignment of an intermediate value to an F variable will mess the results
up), but we discovered at least one app that was relying on the above
kind of calculation working, and which broke when migrating from the 
-rh8x (Red Hat 8.x) to the -el4 (RHEL 4/5 or CentOS 4/5) version.  

Note: this fix will also be retrofitted to 5.0.999.8

2.
---
AIX neg/pos crossover fix:  Similar to the above issue, there was a problem
with calculations involving B or I variables when they crossover over 
the maximum or minimum value (thereby changing from positive to negative).
(This is the same fix as was previously released as 5.0.999.7).

3.
---
APEX bug fix: Files with //GDI directives but with no explicit page 
breaks were causing an infinite loop (creating large output files).
(This combination is not recommended, as the preview proprocessor is 
unable to accurately predict the page break locations that will occur 
with a particular output device, but it no no longer creates havoc.)
Also, a minor problem in which a trailing FF in a proper GDI printfile
was causing the preview to indicate an extra blank page, even though
such trailing FF chars no longer generate a blank page in the real 
output - see 1117.7 notes below.

4.
---
APEX bug fix: The printer init statements LMARGIN and TMARGIN were being
ignored.

============================================================================
A-Shell Development Notes Version 5.1.1117.7 (25 June 2008) 
============================================================================
1.
---
Windows printing bug fix: The last line of a print file was being ignored
if it had no line terminator (except in the case of a trailing FF).  Also,
although arguably the handling of a trailing FF was correct, it didn't
match the way 5.0 handled it.  (For non-PASSTHROUGH, i.e. GDI printouts,
a trailing FF is not needed to eject the page, but apparently some 
applications added one anyway, for historical purposes.)  A-Shell now
ignores a trailing FF when previewing or whenever in non-PASSTHROUGH mode,
provided that the FF is really the very last character of the file.  If 
you want such a trailing FF to have an effect (i.e. eject an extra blank
page), then follow it with a LF or CRLF or even just a space.

2.
---
Windows printing refinement: When the specified printer doesn't exist, or
when previewing with DEVICE=PROMPT:, and the last printer selected no 
longer exists, A-Shell now displays the warning message but then prompts
for a new printer.  Previously it just complained and then aborted the
print operation.

============================================================================
A-Shell Development Notes Version 5.1.1117.6 (25 June 2008) 
============================================================================
1.
---
APEX bug fix:  The EZTYP wrapper for APEX was, in some cases, inappropriately
trying to save and restore the screen, even through this is not necessary
with APEX (since it uses a separate window); this was having some bad
side effects on some GUI programs (like destroying the existing controls).

============================================================================
A-Shell Development Notes Version 5.1.1117.4 (25 June 2008) 
============================================================================
1.
---
NT4 / W98 compatibility improvement:  Trying to launch A-Shell 5.1 under
NT4 or W98 was causing it to crash with a message about failure to link
FlashWindowEx and/or SHGetFolderPath.  These routines are now dynamically 
loaded only on demand.

============================================================================
A-Shell Development Notes Version 5.1.1117.1 (20 June 2008) 
============================================================================
1.
---
FTPDLX bug fixes:  1) transferring a file to/from the root directory of 
a device was generating a strange error message and aborting the transfer.
2) the automatic re-registration of ftpdlxcall2.dll that occurs on the 
first FTP transfer for a session was registering the 5.0 version of the 
module (in some cases leading to an error creating the COM instance).

============================================================================
A-Shell Development Notes Version 5.1.1117.0 (16 June 2008) 
============================================================================
1.
---
AUTLOG.SBR refinements: default minimum buffer size increased from 3000 to
7200, and error messages improved slightly.

2.
---
MIAME.INI refinement:  It is now possible to insert comments (starting
with either ; or #) above the SERIAL= line in the MIAME.INI.  The INI also
now supports an optional [MIAME] section header at the top (making it 
easier to use standard INI-processing routines, including INIX.SBX, for
updating it).

============================================================================
A-Shell Development Notes Version 5.1.1116.6 (13 June 2008) 
============================================================================

1.
---
FTPDLX Refinements:  FtpDLXcall2.DLL 5.1.0.204 now supports flag 512
(rename host file after copy) in conjunction with wildcarding. Also, when
wildcards are specified, an additional log file, ftpdlx.lst, will be 
created showing the wildcard and the matching files, and if the renaming
option is on, the ftpdlx.log file will also show each individual rename.
Also, if the remote server doesn't allow renaming if the target already
exists, FTPDLX will send an explicit delete command and then try renaming.

============================================================================
A-Shell Development Notes Version 5.1.1116.5 (11 June 2008) 
============================================================================
1.
---
Bug fix: EZTYP was aborting with a memory allocation failure on large
files.  (Affected UNIX versions only).

============================================================================
A-Shell Development Notes Version 5.1.1116.4 (11 June 2008) 
============================================================================
1.
---
Bug fix: EZTYP wasn't performing the auto-switch to 132 column mode.

2.
---
Compiler bug fix: /CI (case insensitive) wasn't working with functions.
New version of standalone compiler: 1.2(403)

3.
---
MEM: device bug fix: Basic LOOKUP statement wasn't recognizing the MEM:
device (or AUTO_MEMOPEN).  In addition to the fix, LOOKUP operations are
now traced when the FOPENS trace flag is set.

============================================================================
A-Shell Development Notes Version 5.1.1116.3 (10 June 2008) 
============================================================================
1.
---	
Fix EZTYP failure in A-Shell/Linux -el4 (RHEL/CentOS) version.

============================================================================
A-Shell Development Notes Version 5.1.1116.2 (10 June 2008) 
============================================================================
1.
---	
Memory File I/O bug fix:  The EOF flag was being set one INPUT statement
too soon when inputting from a file loaded into user memory
(either by referencing the MEM: device or by using the OPTIONS=AUTO_MEMOPEN).
That is, it was being set after returning the last line of the file, 
instead of waiting for the next attempt to read when there was no more 
data.

Note that the EOF flag really means that we hit EOF before completing the
operation.  It does not mean that no data was returned.  If the last line
of a file does not end with a terminator (CRLF or LF), then the EOF flag
will be set at the end of returning the last line, even though valid data
was input. So to be really sure you are processing all the data in a file,
do not assume that EOF means that no data was input.  For example:

    do 
        input line #ch, pline
        if eof(ch)=1 exit
        <process pline>
    loop

The above loop is typical but fails to process the last line of the file 
if that line was not terminated with a CRLF or LF.  

    do while eof(ch) = 0
        input line #ch, pline
        <process pline>
    loop

The above loop solves that problem, but will process a null line at the 
end of the file if the last line was properly terminated.  To avoid that,
you need an additional test...

    do 
        input line #ch, pline
        if eof(ch)=0 or pline#"" then
            <process pline>
        else
	    exit   
        endif
    loop

The above loop handles both cases properly, processing each line if either
EOF has not yet been reached, or if data was input (even if the EOF was 
reached).

2.
---
ATE enhancement:  You can now pass arbitrary command line arguments from
ATE to ASHW32 using a new meta-parameter:

    -ashargs "xxxxxx"

Where "xxxxxx" is any set of legal ASHW32 command line switches, provided
they themselves do not contain any quotes.  For example:

    "c:\program files\ate\bin\ate.exe" -ashargs "-mx -m" myprofile

The switches -mx and -m will be inserted into the ASHW32 command line
used by ATE to launch the emulation session.

============================================================================
A-Shell Development Notes Version 5.1.1116.1 (09 June 2008) 
============================================================================
1.
---	
XTREE enhancement: file mode now supports cformat "o" to allow the previous
cell to overflow and merge into the current cell if the current cell is 
empty.  Note that this could affect the layout of the returned item in the
array parameter, so if it is critical to you that all spaces be preserved
in that line, don't use this code.

2.
---
MX_GETOFD (95) refinement:  In the case of error 0x3002, it now reports
additional information ("invalid filename" and the text of the passed in
filename.)

3.
---
ATE version mismatch workaround:  When running A-Shell 5.1 and ATE 
5.0.9997.4 or below, the MIAMEX,MX_GETOFD was aborting with error 0x3002.
This update checks the ATE version, if applicable, and implements the 
workaround to improve backwards compatibility.

============================================================================
A-Shell Development Notes Version 5.1.1116.0 (08 June 2008) 
============================================================================
1.
---	
Imaging enhancement: Add rudimentary support for PNG image format, via 
AUI_IMAGE, IMAGE.SBR, AUI_CONTROL, //IMAGE, and XTREE.  (Saving scanning 
images to PNG not yet supported, nor is the alpha channel, except in XTREE.)

File extension must be PNG or WMF.  (The latter is a weird case - apparently
in some cases WMF files may actually be PNG files.)   Several new PNG-
specific error status codes added to the AUI_IMAGE functions:

-100 	Unknown critical chunk
-101 	Not enough IDATs for image
-102 	Invalid IHDR chunk
-103 	Invalid bit depth in IHDR
-104 	Invalid color type in IHDR
-105 	Invalid color type/bit depth combo
-106 	Invalid interlace method in IHDR
-107 	Invalid compression method in IHDR
-108 	Invalid filter method in IHDR
-109 	Invalid image size in IHDR
-110 	Bad PNG signature
-111 	Bad CRC value
-112 	Extra data at end of file
-113 	Unexpected End Of File
-114 	Memory error
-115 	Decompression error
-116 	Compression error
-117 	Out of disk space

2.
---
INMEMO refinement:  HOME and Control+E (END) now supported in display
paging mode.

3.
---
XTREE fix: ClickExit and HdrClickExit definitions for column 1 were acting
as the default for all other columns.  

4.
---
XTREE fix: ClickExit and HdrClickExit exits weren't always setting 
XROW and XCOL correctly.  (TARGETROW/TARGETCOL were ok.)

============================================================================
A-Shell Development Notes Version 5.1.1115.4 (06 June 2008) 
============================================================================
1.
---
INFLD bug fix: raw input (TYPE @) was not setting exitcodes for function
keys.  

============================================================================
A-Shell Development Notes Version 5.1.1115.3 (05 June 2008) 
============================================================================
1.
---
Bug fix: EZTYP was not working under UNIX.

2.
---
W98 workaround: ASHW32.EXE 5.1 now works under W98.  Previously it failed
to launch, reporting an error linking PrtDlgEx.  (Note that for various
reasons, you should probably use the "c" version with W98).

3.
---
ASHW32 now warns you when trying to create GUI controls, if your terminal
driver doesn't support graphics.

============================================================================
A-Shell Development Notes Version 5.1.1115.2 (04 June 2008) 
============================================================================
1.
---
Fix bugs relating to recently introduced support for AUTO_MEMOPEN with
sequential input files (see 5.1.1114.0 below):

- Byte value 0xFF was being confused with EOF.
- XCALL GET was crashing when it tried to input from a memory file.
- RUN, LIT, and SBX files, and any file with "in use" flag set, are now
  excluded from AUTO_MEMOPEN consideration.

An example of a program that was failing prior to the above fixes is
DIR/V.  (For example, DIR/V [] was finding itself in memory when trying
to read the version info from the file, then crashing because it uses
XCALL GET to read the binary version info.)

2.
---
MX_REGISTRY fix:  The set operation (opcode 3) wasn't working for DWORD
types.  It was always setting them to 0.

3.
---
XTREE fix: The focus was being lost after using the space bar to toggle
a checkbox or radio button cell.

============================================================================
A-Shell Development Notes Version 5.1.1115.1 (02 June 2008) 
============================================================================
1.
---
Wildcard fix:  COPY, MOVE, and RENAME were not properly handling the
replacement of wildcards in the output spec when the corresponding 
character in the matching input filespec was null.  For example:

	.COPY A?=B?

This as properly copying BX to AX, but it was incorrectly copying B to A?.
(The null byte in the 2nd position of the filename "B" was not replacing
the wildcard "?" in the output.)  The new command versions are:

    COPY.LIT      276-064-513-763   3.2(130)
    MOVE.LIT      276-064-513-763   3.2(130)
    RENAME.LIT    137-624-611-443   3.0(111)

Note: these updates will also work under A-Shell 5.0.  Currently they are
only available via the 5.1 Update Center (ASHUPD) but will probably be 
added to the 5.0 Update Center packages at some point.

Also note that it is not a mistake that MOVE.LIT and COPY.LIT are identical.
(See next item for explanation.)

2.
---
MOVE.LIT enhancement:  MOVE.LIT now works under Windows (previously was 
only under UNIX) and supports all of the switches and syntax options of 
COPY.  (Both are implemented via MIAMEX, MX_COPYFILE, for which the 
difference between MOVE and COPY is just one bit in the FLAGS.)  As with
COMPIL and OCMPIL (another example of two identical programs with different
names), the program checks its own name and runtime to decide which way to
act.

============================================================================
A-Shell Development Notes Version 5.1.1115.0 (30 May 2008) 
============================================================================
1.
---
WINDOWS GDI Printing enhancement:  New printer init parameters:

	XORIGIN=###
	YORIGIN=###

These define the MINIMUM offset from the top left physical corner of
the paper to the 0,0 print position (in twips).  A-Shell and APEX will
operate on the LARGER of the XORIGIN,YORIGIN values and the physical
margin as defined by the printer driver.  So in other words, if you
set them each to 360, you should get AT LEAST 1/4" top/left margin,
even on printers (like some image printers, PDF printers, and even
APEX itself) that don't have any built-in physical margin limitation.  
This can be very useful in reducing the alignment fluctuations between
different printer models caused by differing hardware paper margins.

2.
---
XTREE enhancement: Previously, the COLDEF parameter was ignored in file
mode when the XTF_FCOLDEF flag was set.  Now, the COLDEF parameter may
be used in that situation to add to, or replace the column definition in
the file, and optionally to cause the first several lines of the data
file to be skipped (i.e. so that header or other meta-data can be included
in the file without being interpreted as data by XTREE).  In order for
the COLDEF parameter to be treated as significant (when XTF_FCOLDEF is set),
it must begin with "+", "-", or "=".  Syntax:

    {-skipval}+<COLDEF string>
    {-skipval}=<COLDEF string>
    
The optional {-skipval} clause, which must be first if present at all,
is used to force lines of the data file to be skipped.  If skipval is
a number (e.g. "-5"), then XTREE ignores that number of lines at the top
of the file (not counting the first line, which is interpreted as a 
column definition string due to the XTF_FCOLDEF flag).  If skipval starts
with a character other than 1-9, it is interpreted as a string label 
(31 chars max); data interpretation will start with the line in the file
following the line that starts with the label string.  (Warning: the
label string should not include "+", "-", or "=".)  For example, 
consider this file:

    1~5~Zip~#~7~30~City Name~S~~
    bla bla bla
    bla bla bla
    xtreedata:
    06104 Belmont
    00922 Puerto Nuevo
    <etc>

The file contains a column definition string in the first line, followed
by three non-data lines, followed by N data lines.  To tell XTREE to 
skip over those non-data lines, you could set the COLDEF parameter to
one of the following:

    COLDEF = "-xtreedata:"	! skip until after "xtreedata:" label
    COLDEF = "-3"		! skip 3 lines

Instead of, or in addition to skipping lines, you can also use the COLDEF
parameter to append to, or replace, the column definition string in the 
file. To append, use "+" followed by a legal COLDEF definition string.
Appending is useful when you want to add something non-data specific, such
as a popup menu, which may depend on runtime application logic. To replace, 
use "=" followed by a legal COLDEF definition string.  Replacement is 
probably most useful when you didn't really want to put the column definition
in the file at all, but needed to in order to use the -skipval feature 
(since all of these special COLDEF parameter features discussed here 
require the XTF_FCOLDEF flag).  Some legal examples:

    ! use column definition from the file, as is.
    COLDEF = ""    

    ! skip 3 lines (plus column def line), append popupmenu to col. def.
    COLDEF = "-3+0~0~x~H~PopupMenu=Eat,VK_xF100;Drink,VK_xF101~~

    ! skip to "data:" label, replace col. def entirely
    COLDEF = "-data:=1~5~Zip~#~RGBbg=50,100,200~~7~30~City~S~~

Note that column definition string following the "+" or "=" in the 
examples above must meet all of the normal COLDEF syntax rules, including
ending with ~~.

3.
---
AG_SETCOLOR enhancement:  It is now possible to query the RGB definitions
of any of the A-Shell palette colors using a variation of the AG_SETCOLOR
syntax.  (In this mode, AG_SETCOLOR is a misnomer; a new symbol, 
AG_PALETTE has been added to ASHELL.DEF which has the same value as 
AG_SETCOLOR (15), for anyone bothered by confusion that might be created
by using a function called AG_SETCOLOR to query the colors.)  New syntax:

    ? TAB(-10,AG_PALETTE);ctype,cnum{,r,g,b};chr(127);

ctype: 1=set fg color, 2=set reduced fg color, 3=set bg color,
       4=get fg color, 5=get reduced fg color, 6=get bg color

cnum (same as before): 0-7 to specify the palette entry #

r,g,b (same as before): The R, G, and B values (0-255), used when ctype <= 3.

When ctype >= 4, the command will send back into the keyboard buffer a 
string formatted as "R,G,B" indicating the RGB values currently defined
for the specified palette entry.

4.
---
AG_GETENV enhancement:  The TAB(-10,AG_GETENV) command now optionally 
"de-mangles" paths. New syntax:

    ? TAB(-10,AG_GETENV);"var,1";chr(127);

If the ",1" is appended to the environment variable name, as shown above,
then the result will be "de-mangled" (i.e. converted from the DOS 8.3
compressed format to the full long format), if possible.   For example:

    ? TAB(-10,AG_GETENV);"TEMP",chr(127);

The above command (without the ,1) might return something like:
C:\DOCUME~1\yourname\LOCALS~1\Temp

    ? TAB(-10,AG_GETENV);"TEMP,1",chr(127);

The above command (with the ,1) might return something like:

C:\DOCUMENTS AND SETTINGS\yourname\LOCAL SETTINGS\Temp

5.
---
MX_GETENV enhancement:  A new optional parameter allows the returned
environment variable definition to "de-manged" if applicable:

	XCALL MIAMEX, MX_GETENV, envvar, value {,flag}

If the flag parameter is specified and set to 1, then the returned value
will be de-mangled. (See AG_GETENV above for details.)

6.
---
AUI_CONTROL fix: Setting the parentid parameter for a dialog to -1 (to
force the dialog to be positioned relative to the main window, regardless
of whether there was already a modal dialog defined) wasn't working due
to signed/unsigned arithmetic confusion.

7.
---
Windows Refinement:  The centralized help file loader now reports detailed
error messages when it fails.  Previously it may have remained silent.

============================================================================
A-Shell Development Notes Version 5.1.1114.0 (27 May 2008) 
============================================================================
1.
---
GDI printing enhancement: New printer init commands to affect minor 
horizontal and vertical adjustments to the overall positioning of everything
on the page, except images:

	XOFFSET = ###
	YOFFSET = ###

The units are twips (1440 to the inch), with positive values shifting 
the output down and to the right, negative up and to the left.

The concept here is to make it easier to adjust the output of existing 
reports designed for plain or pre-printed forms, to instead use scanned,
printed-as-you-go forms.  Often this presents difficulties in getting 
the text to line up with the form due to minor fluctuations in the size of
the form image introduced by scanning or scaling to print.

Note that the TMARGIN and LMARGIN commands are not very useful for this 
kind of thing, partly because they operation in such coarse units, partly
because they have other side effects, and partly because they don't affect
X,Y coordinate positioning (in GDI directives).  The XOFFSET and YOFFSET
parameters were designed to overcome these issues and should be used instead.

2.
---
New feature:  The MEM: device, (as well as OPTIONS=AUTO_MEMOPEN), can now
be used with sequential input files.  For example:

	OPEN #1, "MEM:MYFILE.TXT", INPUT

The above statement would work if MYFILE.TXT was loaded into the user
memory (using LOAD MYFILE.TXT).

	OPEN #1, "DSK1:MYFILE.TXT[123,456], INPUT

As with RANDOM files, if OPTIONS=AUTO_MEMOPEN, then the above OPEN 
statement will first check user memory to see if MYFILE.TXT is loaded, 
and if so, will use that copy directly.

============================================================================
A-Shell Development Notes Version 5.1.1113.8 (26 May 2008) 
============================================================================
1.
---
XTREE enhancement: Date columns (D) that include both a date and a time
(e.g. "25-May-08 08:25 PM") will now be sorted taking both into account.

2.
---
XTEXT refinement: HTML browsing mode now automatically sets TXF_FITVIEW 
and TXF_WRAP.  (Without these, the browsing display is likely to be 
empty or corrupt, so there's no good reason not to set them, other than
to leave you wondering why browsing doesn't work.)

============================================================================
A-Shell Development Notes Version 5.1.1113.7 (24 May 2008) 
============================================================================
1.
---
Bug fix: I,2 variables were not holding negatives values correctly under AIX.

2.
---
APEX bug fix: Full page images in the Preview window were being shrunk by
an amount corresponding to the physical top and left margin of the printer.
(The effect was mainly seen on near the right and bottom edges, although 
if you were overprinting the image with precisely-positioned text, it was
appearing slightly off in the Preview.)

============================================================================
A-Shell Development Notes Version 5.1.1113.6 (23 May 2008) 
============================================================================
1.
---
APEX bug fix: using the XTREE Print Preview was corrupting
the saved preview settings, such that when you next tried to preview a
report sent to the PROMPT: printer, you would likely get a "Printer $#s@ 
not found" message.  Thanks to Stephen Funkenhauser for helping resolve
this unusual one.

============================================================================
A-Shell Development Notes Version 5.1.1113.5 (22 May 2008) 
============================================================================
1.
---
XTREE bug fix: FastMax=# was not recognizing a trailing space as counting
against the max.  Also if the shift key was down, it was advancing to the
previous rather than then next field (i.e., the automatic TAB was acting
like Shift-TAB).

============================================================================
A-Shell Development Notes Version 5.1.1113.4 (22 May 2008) 
============================================================================
1.
---
XTREE bug fix: Clicking on an editable radio button was updating the 
button but then immediately losing the focus.  (Probably apparently
introduced in the 60 version of the DLL.)

============================================================================
A-Shell Development Notes Version 5.1.1113.3 (20 May 2008) 
============================================================================
1.
---
XTEXT enhancement: HTML form return data now starts with "&url=<spec>" 
where spec is the URL of the form, or the local filespec.  This is mainly
of interest in the case where hyperlinking is permitted, thus allowing
the user to navigate to a form that might not be the one expected by the
program.  So now the return buffer (when exitcode=30) will look something
like this:
 
   &url=c:\vm\dsk0\908040\demo2.htm&action=mailto:jack@m.com&method=POST&...

See 1112.2 below for more info on HTML forms.

2.
---
Windows Bug fix: fix loophole in XTREE trace logic causing a possible GPF.

3.
---
Windows FTP bug fix: wodftpdlx.dll 2.8.2.415 fixes a problem
introduced in version 2.8.1.413 (included with A-Shell 5.1), in which
the client would simply fail to connect to the server.  (Because the
fix is not in ASHW32.EXE, you'll need to use the Update Center or run 
the installation process again to get a complete update.)  Some of the 
FTP bug fixes covered in this update (since the 2.7.0.303 version which
shipped with 5.0):
 
- Local timezone (with conversion from UTC) is now used in all date-
  related functions.
- IBM directory format support in directory parser
- Fix directory parsing  problems related to making multiple connections 
  with the same instance, due to variables being re-used.
- Fix failure to properly report local disk full error.
- Fix problem in the initial SFTP connection on some Linux servers

4.
---
INFLD GUI refinement: The "correction" introduced in 5.1.1111.1 (see below)
in which INFLD acted as if the caret was at the start of a fully selected
(destructive mode) field has now been backed out, due to complaints of it
affecting existing users who were counting on that bug as a feature.  In 
order to provide a workaround for those wanting the original bug fixed, 
there is a new MIAME.INI option: SBR=INF_GUISELPOS.

5.
---
XTREE refinement:  The FastMax=# clause is now compatible with cell
validation.

6.
---
XTREE bug fix: Trees containing editable checkboxes but no other editable
cells were sometimes getting vertically resized on the first click 
(causing the checkbox focus marker to no longer line up with the actual
row).

============================================================================
A-Shell Development Notes Version 5.1.1113.2 (18 May 2008) 
============================================================================
1.
---
XTEXT.DEF additons:  new symbols TXF#_xxxx added to define all the 
possible flags in TXC'FLAGS1 thru TXC'FLAGS7

2.
---
Enhancement to a proprietary custom subroutine: SBR=XMASCB_OPEN
Adding this option to the miame.in causes the xMASCB routines to optimize
their open/close logic so that files are kept open for the duration of 
the current program. 

============================================================================
A-Shell Development Notes Version 5.1.1113.1 (16 May 2008) 
============================================================================
1.
---
XTREE enhancement: New COLDEF clause FastMax=# sets the number of characters
for an editable text or combo field which can be entered before it 
automatically advances to the next field.  This supercedes InfDef=F, which
no longer does anything.

2.
---
XTREE enhancement: You can now force overwrite mode during editing 
(instead of the normal insert mode) by adding this COLDEF clause:

	InfDef=||I

(||I is the INFLD code to force overwrite mode.)  Note that you most 
likely would want to use this feature in conjunction with non-destructive
mode (InfDef=||Ie), particularly when FastMax=# is being used.

3.
---
XTEXT / HTML refinement:  Temporary download files are now written to
either the ATECACHE directory (if defined), or the TEMP directory 
(if defined), instead of the current directory.

============================================================================
A-Shell Development Notes Version 5.1.1113.0 (15 May 2008) 
============================================================================
1.
---
XTREE bug fix:  The 6.0.1 version of the SftTree_IX86_A_60.dll fixes a
display problem introduced in the 6.0.0 version of the same dll, in which
the horizontal grid lines were in some cases partially wiped out by the
text in the cells.  

Since you need to update the DLL, either re-install from a complete
installation package (.exe) or use the Update Center.

2.
---
Bug fix:  eliminate a spurious "file not found" message box during printing
if the