============================================================================ A-Shell Development Notes Version 5.1.1107.1 (24 Mar 2008) ============================================================================ 1. --- EZTYP cosmetic bug fix: was showing "^M" at the end of each line. ============================================================================ A-Shell Development Notes Version 5.1.1107.0 (14 Mar 2008) ============================================================================ 1. --- New "eXplicit" variations of READ and WRITE statements: XREAD #CH, RECNO, VAR {,VAR2...,VARN} XREADL #CH, RECNO, VAR {,VAR2...,VARN} XREAD'READ'ONLY #CH, RECNO, VAR {,VAR2...,VARN} XWRITE #CH, RECNO, VAR {,VAR2...,VARN} XWRITEL #CH, RECNO, VAR {,VAR2...,VARN} XWRITEN #CH, RECNO, VAR {,VAR2...,VARN} XWRITELN #CH, RECNO, VAR {,VAR2...,VARN} These are equivalent to the standard versions of these statements (without the "X" and without the RECNO variable), except that, instead of getting the record number implicitly, from the variable specified in the OPEN statement, the record number is specified, eXplicitly, in the statement. This can be advantageous in generic or parameterized implementations of file i/o, and especially in SBX routines (which otherwise need to use MX_FLSET in order to access a file that was opened outside of the SBX.) 2. --- New MX_BROWSEFOLDER (170) function for selecting a Windows folder. Similar to the MX_GETOFD, it is useful when you only want to select a folder or other non-file object (such as computer). xcall MIAMEX, MX_BROWSEFOLDER, Folder, RootID, Title, Flags Folder (string,in/out) returns the selected folder (or null if user cancelled). On input specifies the default folder. Note even when the RootID parameter is specified, this default folder specification must be absolute (i.e. not relative to the RootID). But it must specify a folder on or below that RootID folder. RootID (numeric, in) may be used to specify a root folder, above which the user would not be able to navigate. May be any single one of the standard Windows directory CSIDL_xxx identifiers, the most typically useful of which are: CSIDL_APPDATA (&h001a) The common repository for application-specific data. e.g. c:\documents and settings\username\Local Settings\Applicationdata\app (CSIDL_xxx list to be continued...) Title (string,in) specifies the title message which appears in the dialog box. (There is room for 2 or 3 lines of text, which will be auto-wrapped as needed.) Flags (Numeric): BIF_RETURNONLYFSDIRS (&h0001) Return only file system folders BIF_DONTGOBELOWDOMAIN (&h0002) Don't include network folders below the domain level BIF_RETURNFSANCESTORS (&h0008) Only return file system ancestors BIF_EDITBOX (&h0010) Include an edit control in the dialog to allow user to type a path BIF_VALIDATE (&h0020) Don't allow user to type an invalid name in the edit box BIF_NEWDIALOGSTYLE (&h0040) New style of dialog; offers several enhancements over original style (resizing, drag/drop, new folder button, delete, etc.) BIF_USENEWUI (&h0050) Combination of BIF_NEWDIALOGSTYLE and BIF_EDITBOX BIF_BROWSEINCLUDEURLS (&h0080) Allow display of URLs (requires BIF_USERNEWUI+BIF_BROWSEINCLUDEFILES) BIF_UAHINT (&h0100) With BIF_NEWDIALOGSTYLE and not BIF_EDITBOX, displays a standard hint to the user in place of the edit box. BIF_NONEWFOLDERBUTTON (&h0200) Eliminates the "New Folder" button BIF_KBDLOCKLATETARGETS(&h0400) Don't traverse target as shortcut BIF_BROWSEFORCOMPUTER (&h1000) Only allow selection of computers BIF_BROWSEFORPRINTER (&h2000) Only allow selection of printers. (Automatically sets the RootID to CSIDL_PRINTERS unless RootID is already non-zero.) BIF_BROWSEINCLUDEFILES(&h4000) Dialog displays files as well as folders BIF_SHAREABLE (&h8000) Dialog can display shareable resources on remote systems The MIAMEX.BP sample program in [908,30] of the SOSLIB has been updated to illustrate this function. 3. --- New TAB(-10,AG_BROWSEFOLDER); command to access the MX_BROWSEFOLDER function: ? tab(-10,70);Folder,RootID,title,flags;chr(127); input line "", Folder 4. --- New MX_GETSHELLPATH (171) function for retrieving the actual directory path for a specified Windows directory ID (using the CSIDL_xxx values referenced above in MX_BROWSEFOLDER) xcall MIAMEX, MX_GETSHELLPATH, RootID, Folder RootID (numeric, in) - same as RootID in MX_BROWSEFOLDER Folder (string, out) - returns the corresponding directory path. 5. --- New TAB(-10,AG_GETSHELLPATH); command to access the MX_GETSHELLPATH function: ? tab(-10,71);RootID;chr(127); input line "", Folder 6. --- Fix PASSTHROUGH printing bug: was outputting only a blank page (introduced in 5.1). ============================================================================ A-Shell Development Notes Version 5.1.1105.2 (28 Feb 2008) ============================================================================ 1. --- ATSD/APEX Bug fix: In some cases, use of PRINT or XCALL SPOOL under ATSD was causing APEX options to be set as if you were running under a local Windows GUI environment. 2. --- Printing enhancement: the maximum one dimensional tab value has been increased from 472 to 4095. ============================================================================ A-Shell Development Notes Version 5.1.1105.1 (25 Feb 2008) ============================================================================ 1. --- Fix bug in OPTIONS=GUI_SPC_IND (introduced in 1104.3); was having unwanted effects on some non-static controls (like INFLD). ============================================================================ A-Shell Development Notes Version 5.1.1105.0 (20 Feb 2008) ============================================================================ 1. --- REGEX.SBX bug fix: return STATUS values were mixed up. ============================================================================ A-Shell Development Notes Version 5.1.1104.4 (18 Feb 2008) ============================================================================ 1. --- New ATE command: TAB(-10,AG_OPTIONS);"op,options1,options2";chr(127); (AG_OPTIONS=69). The command allows you to set or retrieve OPTIONS values from the ATE client (similar to MX_GETOPTIONS & MX_SETOPTIONS) but for the ATE client. Op values: 0 = get current options. These are returned in the keyboard buffer in the format options1,options. For example: ? tab(-10,69);"0";chr(127); input "",OPT1,OPT2 1 = set values (using passed options1, and if specified, options2) 2 = set only the option2 value 4 = OR (set) individual bits from options1 and options2. This allows you to set one or more bits without having to first retrieve the current settings (in order to avoid changing existing flags). Note that you can specify options1 or option2 = 0 to avoid changing it. 8 - clear individual bits. In this case, any bit that you specify in options1 or options2 will be cleared from the current settings. Again, you can specify 0 to avoid changing one set of flags or the other. ============================================================================ A-Shell Development Notes Version 5.1.1104.3 (17 Feb 2008) ============================================================================ 1. --- Text-to-GUI Enhancement: OPTIONS=GUI_SPC_IND now fully tokenizes strings containing consecutive spaces in order to preserve the column alignment of the tokens. It also converts tokens made of --------- or ========= to graphic horizontal lines. ============================================================================ A-Shell Development Notes Version 5.1.1104.1 (8 Feb 2008) ============================================================================ 1. --- XTREE bug fixes: same as those for 999.2 2. --- Multi-monitor bug-fix: In certain situations, windows beloning on a secondary monitor in negative space were offset too far to the left to be visible. 3. --- Multi-monitor enhancement: When launching A-Shell, the main window is now repositioned to be visible if otherwise outside the range of the virtual desktop. 4. --- XTREE enhancement: New advanced column option InfDef=xxx opens the door to the ability to specify some variations of XTREE editable cell behaviour using INFLD TYPE codes. Currently this only applies globally for all columns in the tree, and only the following TYPE codes are supported: e force non-destructive ) start cursor at end of field, requires e ============================================================================ A-Shell Development Notes Version 5.1.1104 (4 Feb 2008) ============================================================================ 1. --- ATE 5.0 and 5.1 now have separate COM identifiers, so they can be run in parallel. Note: this also means that any COM XCALLs, such as FTPDLXCALL.DLL, are also specific to 5.0 or 5.1. (If you have created your own COM XCALLs, contact us for details on converting them to 5.1). 2. --- APEX fix: Spooler switches (such as /LANDSCAPE) are now passed to child sessions, i.e. from A-Shell to APEX. ============================================================================ A-Shell Development Notes Version 5.1.1103.2 (29 Jan 2008) ============================================================================ 1. --- New XTREE coldef option: HdrLines=# Analogous to the TotalLines=# option, this allows you to specify a number of lines at the top of the tree that are to be treated as fixed headers and thus not included in sorting. ============================================================================ A-Shell Development Notes Version 5.1.1102.3 (22 Jan 2008) ============================================================================ 1. --- New EZSPL.SBR/SPOOL.SBR SWITCHES parameter values: 524288 = Force APEX Preview on (requires APEX on the client) 1048576 = Force APEX Preview off 2. --- New PRINT.LIT 3.0(123) switches: /PREVIEW /NOPREVIEW /SW:#### The first two override the APEX (GUI Print Preview) defaults on the client. The last is a alternate way of passing switches, instead of by name, you can pass the sum of the numeric switch values (as you would in the SWITCHES parameter of SPOOL.SBR/EZSPL.SBR). 3. --- New EZ-SPOOL configuration file command: SWITCHES = {+/-}##### This allows you to add, remove, or replace the SWITCHES passed in the XCALL EZSPL, xcall SPOOL, or even XCALL EZTYP. For example, SWITCHES = +524288 would force EZSPL (including EZTYP) to act as if the 524288 (GUI PREVIEW) switch had been set by the caller, and thus would launch the new GUI Preview utility instead of the text preview. Currently the main value of this is probably that it allows you to force EZTYP to use the new Preview utility, provided you are running under A-Shell/Windows. (For A-Shell/UNIX, there is probably no need for this, or I need to think about it more.) ============================================================================ A-Shell Development Notes Version 5.1.1101 (2 Jan 2008) ============================================================================ 1. --- New AUI_CONTROL ctype2 flag: CMF2_PIXCOORDS (&h00000020) allows the coordinates of a control to be specified in pixels rather than in row/col units. ============================================================================ A-Shell Development Notes Version 5.1.1100 (7 Nov 2007) ============================================================================ 1. --- Rewrite the GDI printing code to support an add-on print preview mechanism (APEX) to be offered as an add-on component. 2. --- New XTREE opcode (in xtr'opcode): XTROP_PRINT (6) This option invokes a variation of the APEX Print/Preview facility to allow the contents of the specified XTREE to be printed, with an initial print preview mode. Unfortunately this cannot be invoked in such a way as to allow the XTREE data to be merged with other application-generated data in the same report, but may still be a useful utility function. Note that you can also invoke the operation from the special control dialog reachable via Control+Shift+Double-Right-Click. 3. --- New REGEX.SBR - regular expression processor. REGEX.SBR uses the Open Source Perl-Compatible Regular Expression (PCRE) library. Some form of this is typically already installed on most UNIX systems, or can be acquired from www.pcre.org. For Windows, it requires PCRE.DLL, which is now included with A-Shell 5.1. For details on the syntax of regular expressions, see the Perl Regular Expression documentation at http://perldoc.perl.org/perlre.html. The two most common uses of regular expressions are to extend the power and flexibility of string searches, and to check for valid syntax in a string. The main downside of regular expressions is that they are rather cryptic. For example, a regular expression to match a valid email address word-delimited within a larger string, is: "\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,4}\b" Fortunately, there are many websites containing tutorials and ready-to-use examples for common tasks. The above comes from www.regular-expressions.info (which you should consult before using it directly, since there are some caveats, limitations, and trade-offs to be considered relating to exactly what kinds of email addresses you are allowing. Regular expression processing internally consists of two separate operations: - compiling the expression (checking for syntax errors) - using the expression to match against subject string(s). The A-Shell implementation in REGEX.SBR combines these two, automatically performing the compilation on any pattern passed to it. However, since compilation does involve cpu overhead, and since the same pattern is often used against many subject strings, you can avoid redundant recompilation by setting the PATTERN="" for subsequent matching operations with the same pattern. Syntax: XCALL REGEX, PATTERN, STATUS, SUBJ {, FLAGS, STPOS, MATCH1, ... MATCHN} PATTERN (string) Regular expression (without the Perl-style leading/trailing slash). If "", then use previous one (saves recompiling it) STATUS (f or i) Return codes (0 = OK) (see below) SUBJ (string) Subject string to test against the pattern FLAGS (f or b4) options flags (see below) STPOS (int) starting position in SUBJ MATCHn (string) optional returned matches (for subexpressions) RETURNED STATUS VALUES: >0 Matching success (# of matches) -96 Unable to load PCRE library (PCRE3.DLL under Windows) -97 Unable to allocate memory for library -96 Unable to link to pcre_compil2 or pcre_exit function in lib Pattern compilation errors: -101 \ at end of pattern -102 \c at end of pattern -103 unrecognized character follows \ -104 numbers out of order in {} quantifier -105 number too big in {} quantifier -106 missing terminating ] for character class -107 invalid escape sequence in character class -108 range out of order in character class -109 nothing to repeat -110 [this code is not in use] -111 internal error: unexpected repeat -112 unrecognized character after (? -113 POSIX named classes are supported only within a class -114 missing ) -115 reference to non-existent subpattern -116 erroffset passed as NULL -117 unknown option bit(s) set -118 missing ) after comment -119 [this code is not in use] -120 regular expression too large -121 failed to get memory -122 unmatched parentheses -123 internal error: code overflow -124 unrecognized character after (?< -125 lookbehind assertion is not fixed length -126 malformed number or name after (?( -127 conditional group contains more than two branches -128 assertion expected after (?( -129 (?R or (?[+-]digits must be followed by ) -130 unknown POSIX class name -131 POSIX collating elements are not supported -132 this version of PCRE is not compiled with PCRE_UTF8 support -133 [this code is not in use] -134 character value in \x{...} sequence is too large -135 invalid condition (?(0) -136 \C not allowed in lookbehind assertion -137 PCRE does not support \L, \l, \N, \U, or \u -138 number after (?C is > 255 -139 closing ) for (?C expected -140 recursive call could loop indefinitely -141 unrecognized character after (?P -142 syntax error in subpattern name (missing terminator) -143 two named subpatterns have the same name -144 invalid UTF-8 string -145 support for \P, \p, and \X has not been compiled -146 malformed \P or \p sequence -147 unknown property name after \P or \p -148 subpattern name is too long (maximum 32 characters) -149 too many named subpatterns (maximum 10,000) -150 [this code is not in use] -151 octal value is greater than \377 (not in UTF-8 mode) -152 internal error: overran compiling workspace -153 internal error: previously-checked referenced subpattern not found -154 DEFINE group contains more than one branch -155 repeating a DEFINE group is not allowed -156 inconsistent NEWLINE options -157 \g is not followed by a braced name or an optionally braced non-zero number -158 (?+ or (?- or (?(+ or (?(- must be followed by a non-zero number Matching errors: -1 The subject string did not match the pattern. -2 Either code or subject was passed as NULL, or ovector was NULL and ovecsize was not zero. -3 An unrecognized bit was set in the options argument. -4 PCRE stores a 4-byte "magic number" at the start of the compiled code, to catch the case when it is passed a junk pointer and to detect when a pattern that was compiled in an environment of one endianness is run in an environment with the other endianness. This is the error that PCRE gives when the magic number is not present. -5 While running the pattern match, an unknown item was encountered in the compiled pattern. This error could be caused by a bug in PCRE or by overwriting of the compiled pattern. -6 If a pattern contains back references, but the ovector that is passed to pcre_exec() is not big enough to remember the referenced substrings, PCRE gets a block of memory at the start of matching to use for this purpose. If the call via pcre_malloc() fails, this error is given. The memory is automatically freed at the end of matching. -7 This error is used by the pcre_copy_substring(), pcre_get_substring(), and pcre_get_substring_list() functions (see below). It is never returned by pcre_exec(). -8 The backtracking limit, as specified by the match_limit field in a pcre_extra structure (or defaulted) was reached. See the description above. -9 This error is never generated by pcre_exec() itself. It is provided for use by callout functions that want to yield a distinctive error code. See the pcrecallout documentation for details. -10 A string that contains an invalid UTF-8 byte sequence was passed as a subject. -11 The UTF-8 byte sequence that was passed as a subject was valid, but the value of startoffset did not point to the beginning of a UTF-8 charac- ter. -12 The subject string did not match, but it did match partially. See the pcrepartial documentation for details of partial matching. -13 The PCRE_PARTIAL option was used with a compiled pattern containing items that are not supported for partial matching. See the pcrepartial documentation for details of partial matching. -14 An unexpected internal error has occurred. This error could be caused by a bug in PCRE or by overwriting of the compiled pattern. -15 This error is given if the value of the ovecsize argument is negative. -21 The internal recursion limit, as specified by the match_limit_recursion field in a pcre_extra structure (or defaulted) was reached. See the description above. -23 An invalid combination of PCRE_NEWLINE_xxx options was given. Options flags (for compiling) PCRE_ANCHORED If this bit is set, the pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string that is being searched (the "subject string"). This effect can also be achieved by appropriate constructs in the pattern itself, which is the only way to do it in Perl. PCRE_CASELESS If this bit is set, letters in the pattern match both upper and lower case letters. It is equivalent to Perl's /i option, and it can be changed within a pattern by a (?i) option setting. In UTF-8 mode, PCRE always understands the concept of case for characters whose values are less than 128, so caseless matching is always possible. For characters with higher values, the concept of case is supported if PCRE is com- piled with Unicode property support, but not otherwise. If you want to use caseless matching for characters 128 and above, you must ensure that PCRE is compiled with Unicode property support as well as with UTF-8 support. PCRE_DOLLAR_ENDONLY If this bit is set, a dollar metacharacter in the pattern matches only at the end of the subject string. Without this option, a dollar also matches immediately before a newline at the end of the string (but not before any other newlines). The PCRE_DOLLAR_ENDONLY option is ignored if PCRE_MULTILINE is set. There is no equivalent to this option in Perl, and no way to set it within a pattern. PCRE_DOTALL If this bit is set, a dot metacharater in the pattern matches all char- acters, including those that indicate newline. Without it, a dot does not match when the current position is at a newline. This option is equivalent to Perl's /s option, and it can be changed within a pattern by a (?s) option setting. A negative class such as [^a] always matches newline characters, independent of the setting of this option. PCRE_EXTENDED If this bit is set, whitespace data characters in the pattern are totally ignored except when escaped or inside a character class. White- space does not include the VT character (code 11). In addition, charac- ters between an unescaped # outside a character class and the next new- line, inclusive, are also ignored. This is equivalent to Perl's /x option, and it can be changed within a pattern by a (?x) option set- ting. This option makes it possible to include comments inside complicated patterns. Note, however, that this applies only to data characters. Whitespace characters may never appear within special character sequences in a pattern, for example within the sequence (?( which introduces a conditional subpattern. PCRE_MULTILINE By default, PCRE treats the subject string as consisting of a single line of characters (even if it actually contains newlines). The "start of line" metacharacter (^) matches only at the start of the string, while the "end of line" metacharacter ($) matches only at the end of the string, or before a terminating newline (unless PCRE_DOLLAR_ENDONLY is set). This is the same as Perl. PCRE_UNGREEDY This option inverts the "greediness" of the quantifiers so that they are not greedy by default, but become greedy if followed by "?". It is not compatible with Perl. It can also be set by a (?U) option setting within the pattern. LICENSE NOTES: PCRE is covered under the BSD license, which requires the following notes be included in the documentation included with A-Shell: Written by: Philip Hazel Email local part: ph10 Email domain: cam.ac.uk University of Cambridge Computing Service, Cambridge, England. Copyright (c) 1997-2008 University of Cambridge All rights reserved. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. See the sample programs in [908,46] of the SOSLIB for examples,testing.