This document is a record of the changes made to A-Shell 6.5, beginning with build 1600 of May 2017. Changes to the previous versions of A-Shell can be found with their respective software releases on the A-Shell downloads page.

Organization

The notes in this document are shown twice:

•   Notes by Version and Date: Includes all A-Shell changes regardless of type or significance.

•   Notes by Subject: Does not include bug fixes.

Navigation

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

Text Colors

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

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

•   Items such as bug fixes and minor revisions, which are not being so transferred (teal).

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

Compiler/language (edit 861) and runtime tracing enhancement: syntax for the xxxxxx.PRINT and xxxxxx.PAUSE statements (eg. TRACE.PRINT, DEBUG.PAUSE) expanded to support a debug level, selection tags, multiple expressions, and automatic labeling of traced variables.

<TRACE|DEBUG>.<PRINT|PAUSE> {({level},{tags})} expr1{,expr2,...,exprN}

The optional (level, tags) clause may be used to specify the minimum debug level needed to activate this trace, and/or a list of tags that can be used for selecting or filtering which of these statements is enabled at runtime. If not specified, the default level is 0 for TRACE.xxx and 1 for DEBUG.xxx. Tags, if specified, must be in the form of a string literal (quoted) comma-delimited list of case (not case sensitive). Some examples:

debug.print "var1"=var1

trace.print (1) "var1"=var1

debug.print ("beta,i/o,2.0") var3,var4

trace.pause (27,"fn'foo,alpha") "total="+totx

The first example demonstrates the prior syntax and the fact that the new clauses are entirely optional.

The second example uses the new clause to specify a debug level of 1, which makes the trace.print equivalent to debug.print (illustrating that the only difference between trace.xxx and debug.xxx is the default debug level). It also illustrates that you can specify just the level without the tags argument.

The third example illustrates the use of a tags list without an explicit level (which defaults to 1 for debug.print). It also illustrates the use of multiple values (i.e. a comma delimited list of values, as allowed in a normal PRINT statement). Although not obvious from the syntax, another enhancement in this release is that any variable appearing by itself as a term in the expression list will automatically be prefixed by a label indicating the name of the variable being traced. In other words, if var3=30 and var4="foo", then the trace will look something like: "var3=[30], var4=[foo]". Note that these automatic print labels are only created for variables that appear as terms by themselves in the list of expressions to trace.

The last example shows the case where both a level (27) and a set of tags "fn'foo,alpha" are specified. Note that the totx in the expression list will not get an automatic label because it is already part of a string expression.

Backwards compatibility note: while the new tracing capabilities do rely partly on updates to the runtime system, programs using the new syntax and compiled with the new compiler will remain compatible with older runtimes. (The output will not be as pretty, and the level and tags arguments will display at the end of each output line, but they won't otherwise interfere.)

Tracing enhancement: SET.LIT 1.2(162) now supports expanded DEBUG options in order to take advantage of the expanded trace statement options:

The standard SET DEBUG <level> command is unchanged, except that the maximum has been increased from 9 to 2^31. Note that except for programs which explicitly map a variable named DEBUG, the runtime system will recognize DEBUG as a special system variable whose value is that specified by the SET DEBUG <level> command.

The DEBUG MIN option allows you set a minimum level, such that only those trace/debug statements specifying a level >= the DEBUG MIN level and <= the DEBUG level will be activated. The idea here is to allow different developers to set exclusive ranges so that they can easily enable their own debug traces independent of others'. Or to use different ranges for different modules (although the tags might be more suited for that).

The DEBUG TAGS option allows you to specify a list of tags (comma delimited) to be matched up with the tags in the actual trace/debug statements for the purposes of filtering which will be enabled. Tags are not case sensitive. If the list starts with "+", then individual traces will be enabled if they meet the debug level criteria OR they contain a matching tag. Otherwise statements to be enabled must match both criteria, i.e. satisfy the level AND match one of the tags.  Note that setting the DEBUG TAGS list to "" is equivalent to a wildcard matching all tags. But within the trace/debug statements themselves, and empty tag list matches only an empty DEBUG TAGS list.

To select statements by level without regard to tags, set the DEBUG TAGS to "". To select statements by tags without regard to level, specify a DEBUG TAGS list starting with "+". (To exclude traces that don't contain matching tags, use the DEBUG and/or DEBUG MIN levels to make sure that they won't match up with any of your traces. For example, if all of your trace statements are of the form DEBUG.xxx, instead of TRACE.xxx, or all of them explicitly specify a non-zero level, then just use SET NODEBUG to make sure that none are selected on the basis of the debug level. Alternatively, set the DEBUG MIN level higher than the DEBUG level.)

Note that all TRACE.xxx and DEBUG.xxx statements automatically have a special tag associated with them that matches the current program name, so to select only traces for that program, use the technique just described with SET DEBUG TAGS +program.

The DEBUG OUTPUT option controls where the trace/debug output messages go. The options for <dest> are:

Compiler enhancement (included in edit 861) : new ++PRAGMAs to support enhanced tracing:

++PRAGMA TRACE_BEGIN   {optionlist}

++PRAGMA TRACE.END     {optionlist}

++PRAGMA TRACE.OPTIONS {optionlist}

TRACE_BEGIN and TRACE_END may be used to bracket a section of code for which automatic TRACE.PRINT statements will be generated after each program statement. Each auto-generated trace will consist of two lines: first the source code, then the trace of the variables in that statement. Note that not all statements will be traced; primarily it is limited to those statements which operate on variables. Also note that the trace generally occurs after the statement execution, which means that function and procedure call statements show up in the trace output after the routine returns. IF statements are an exception in that they get traced prior to execution (so you can see the IF statement regardless of whether the condition is true or false).

TRACE_BEGIN / TRACE_END blocks cannot be nested, but a TRACE_BEGIN doesn't necessarily require a corresponding TRACE_END (the end of the source code will imply as much). This allows you to simply insert a ++PRAGMA TRACE_BEGIN anywhere in a program, including the very top, to trace everything from that point on.

The TRACE_OPTIONS pragma only establishes default options for subsequent manually typed xxxxx.PRINT and xxxxx.PAUSE statements (except for those which already include their own explicit options).

The optionlist, which is optional in all three cases, consists of:

(dbglvl, tags, prefix)

Each field is itself optional, although in order to specify a subsequent field, you must specify the prior ones. The parentheses are optional if only the dbglvl field is specified; otherwise they are mandatory.

dbglvl sets the debug level for the statement; the higher the level, the higher the corresponding DEBUG system variable must be in order to activate the statement.

tags is a quoted literal string consisting of comma-delimited symbols to be associated with each xxxxx.PRINT or xxxxx.PAUSE statement.

prefix is a quoted literal string which, if specified, is inserted at the start of each xxxxx.PRINT / xxxxx.PAUSE statement, typically used to specify macros like $#, $T, $P, $L, etc. It comes in handy in situations where you already have a lot of xxxxx.PRINT statement in the program, but are having trouble identifying them in the trace output. Rather than manually modifying each statement to include additional contextual identifiers, you could simply specify ++PRAGMA TRACE_OPTIONS (0,"","$L") to insert the location counter into each trace.

For all three PRAGMAs, the optionlist establishes the default options for subsquent manual or auto-generated xxxxx.PRINT statements.

Language runtime refinement: when an assignment is made to a substring (aka slice) of a dynamic variable, the variable is now expanded as needed for the referenced slice to be part of the variable. For example:

map1 var,x,0

var[9;3] = "foo"

print var[9;3]

Previously, the print statement would have printed nothing; the assignment statement would have had no effect, since the variable var was not long enough for the [9;3] slice to be applicable.

Now, it will be expanded, with leading bytes filled with spaces for string type variables or nulls for X type variables, so that the print statement will always display "foo".

This brings the behavior more into line with the expectation for dynamic variables, which are normally expanded as needed during assignment statements. But the slice assignment has always been a very special case.

New subroutine MX_SRCHPATH (191) searches for a file in the system path.

xcall MIAMEX, MX_SRCHPATH, file, foundpath

Parameters

file  (String)  [in]

filename to search for (no wildcards or directory)

foundpath  (String)  [out]

returns "" if not found, else the full path.

Comments

The search path is system dependent, but normally includes the current directory, the directory from which the A-Shell executable was loaded, plus all the directories included in the PATH environment variable.

One use would be to check whether a particular external command exists before attempting to launch it via HOSTEX.SBR.

GDI printing enhancement: the x,y coordinates in all //GDI directives may now be optionally be expressed relative to the current cursor position by prefacing the coordinate value with "+" or "-". For directives with more than one x,y pair (such as //RECTANGLE or //POLYGON), any relative coordinates are treated as relative to the prior coordinate on the same axis. Some examples:

//;absolute coordinates - from (100,200) to (300,400) ...

//RECTANGLE,100,200,300,400

//;relative coordinates - from 50 units above the current x,y cursor,

//;extending 200 to the right and 75 down

//RECTANGLE,+0,-50,+200,+75

Notes:

•   While mathematically N is the same as +N, within the context of GDI directives, they are all strings, allowing the +N to be recognized and treated differently than N—i.e. as relative rather than absolute.

•   To preserve backwards compatibility, those directives that intepreted -1,-1 as the current position will continue to do so.

•   The //IMAGE directive continues to support negative right and bottom coordinates as indicating width and height. (Fortunately, there is no particular need for negative widths or heights, so nothing is lost by treating negative and positive relative right and bottom coordinates the same here.)

XTREE enhancement: new Advanced Coldef Option RGBfgbg provides capability to specify foreground and background colors for individual cells. The setup is similar to that for the cformat code B, whereby the first space of the cell is reserved for an optional code that references an RGB color, except that in this case, the color reference is to a pair of RGB colors (foreground and background).

There are three parts to configuring this capability:

•   Add the cformat code "BC" to the column definition, which signifies that the first byte of the column data is reserved for the color index character (A-Z,a-z) or blank to indicate the standard/default color. Note that although "BC" may be seen as a sort of combination of the individual B and C codes, the interpretation of the combined "BC" code completely replaces their individual meanings.

•   Define a set of RGB values associated with index characters using RGBfg and/or RGBbg clauses, in the usual way, e.g. RGBbg=50,100,150,A. These colors and their associated index codes may or may not be used for other purposes in the tree, but they are needed in order to define the color pairs used by the "BC" columns.

•   Specify one or more RGBfgbg clauses which associate a new color index code in the same A-Z,a-z range, with a pair of individual color index codes:

RGBfgbg=fgbg(fg,bg);fgbg(fg,bg)...

     e.g.

RGBfgbg=A(A,B);f(Z,q);r(M,);P(,p);Z(,)

Each RGBfgbg clause can contain one or more fgbg(fg,bg) tuplets separated by semicolons. Each tuplet starts with a mandatory index character (A-Z,a-z) which will be used to refer to the combined fg/bg color pair. The fg and bg codes representing the foreground and background colors are each optional (although the comma is mandatory); if omitted, that part of the color pair reverts to the default.

Note that although the individual RGB index characters and the combined FG/BG index characters both occupy the same range (A-Z,a-z), they refer to different tables of colors. So you can have 52 individual colors associated with an index character, and in addition, up to 52 combined pairs associated with an index character. For a given index character, XTREE knows whether to refer to the individual or combined color table by the context, e.g. if the column definition contains "BC", then it will refer to the combined color table, whereas if it contains only "B" or "C" then it would refer to the individual table. However, if you have fewer than 26 of each type of color index you may want to use upper case for one type and lower for the other, just to reduce confusion.

For example:

coldef += "0~0~x~H~RGBbg=50,100,150,A~RGBbg=75,125,175,B~~"

coldef += "0~0~x~H~RGBfgbg=A(A,B);B(B,A);C(A,);D(,B);z(,)~~"

The first line defines two individual RGB colors, indexed as A and B. The second line defines five fg/bg pairs, indexed as A, B, C, D, and z. (We only partially followed the advice just given to separate the two types of indices by upper and lower case.)

The combined fg/bg index character A refers to foreground color A (50,100,150) and background color B (75,125,175). Combined fg/bg index character B refers to the same pair, but with foreground and background refersed. The combined fg/bg index character C refers to the A foreground color with the default background color. D refers to the default foreground color with background color B. And z is equivalent to " " since both the foreground and background colors of the pair are omitted, i.e. set to default.)

A new sample program XTRAFGBG in EXLIB [908,21] has been posted to illustrate this feature.

Compiler bug fix/refinement, edit 859: the starting key in a FOREACH statement may now be any kind of expression. Previously, it only allowed a simple variable or a literal string or numeric constant. And in the case of the numeric constant, although neither the compiler nor runtime complained, the value wasn't being converted to string before treating it as a key, so the resulting starting point of the FOREACH loop was not as expected.

As of this compiler release, any kind of expression that could appear on the right side of an assignment statement is allowed, including numeric expressions. But be advised that in the case of a numeric value, the decimal point and any digits to the right of it are dropped, e.g. 1.9 is treated as "1". If you really want to use a starting key of something like "1.9", then you should explicitly format it using a mask.

Note that these changes are contained within the ASHNET 1.11.162 library update and are not actually dependent on any particular A-Shell version.

•   Support secure protocols TLS 1.1 and TLS 1.2 in HTTP.SBR via the new flags:

•   Fix problems with the ashnet.log file (XHTTPF_DEBUG) not getting written or released under some circumstances.

•   Remove 100 character limit on header lines included at the top of the request (using XHTTPF_HDRBODY). Maximum length is now unlimited, which is useful when headers include lengthy signatures or digests.

•   Append a connection failure code to the XHTTPF_GETSTSTXT return string, as well as the ashnet.log file to assist with debugging failed connections. See the A-Shell Reference > HTTP.SBR > Connection Failure Codes for a listing of the codes and meanings.

When passing expressions to/from functions and SBX subroutines, if the target is type X, use a physical rather than logical transfer. This matches the behavior of assignments, and closes a loophole that previously occurred when the source expression was of the form VAR[x;y] or VAR[x,y] where VAR was of type X. Previously the transfer was being terminated at the first null even when the target variable was of type X.

Note that this change affects all variations of XGETARG and XPUTARG, as well as implicit parameter passing to functions/procedures, potentially changing the runtime behavior of existing compiled programs, but only in cases where a string or non-numeric expression is passed to an X type variable. Given the narrow range of situations affected, and our belief that the new behavior is more in line with how programmers thought that it had been working all along, not to mention the fact that it is now consistent with the assignment statement logic, we feel that the upside of the change overwhelms the downside. Nevertheless, at least for now, we are not treating it as a bug fix and therefore not planning to retrofit into the stable 6.4 release. Programmers concerned about whether this might affect them are advised to do a global source code search for occurrences of "[" within an XCALL or func/proc call parameter list, as well as within any "PUTARG" statement and then check to see whether the receiving variable is of type X and whether you are counting on the expression being terminated by the first null.

New opcode CRYPTOP_HMAC allows CRYPTO.SBR to create HMACs (Hash-based Message Authentication Codes), commonly used for signing web service requests. They combine a hash/digest algorithm (e.g. SHA256) with a cryptographic key (typically pre-shared between sender and receiver) to both verify data integrity of a message and authenticate the sender.

xcall CRYPTO, CRYPTOP_HMAC, status, src, decoding, dst, encoding, cflags, cipher, key {, keybits, cmode, padding, cbsrc}

Parameters

src and decoding

specify the source message and decoding, as with other opcodes.

dst and encoding

specify the destination for the output of the function. Typically it is encoded using base64 or hex so as to make it easily insertable into a web document. The destination length is independent of the source length and instead is determined by the hash function—e.g. SHA256 results in 32 bytes raw, 43 for base64, 64 for hex.

cflags

used as for the other opcodes

cipher

should be set to CRYPTO_CIPHER_NA (0)

key

as for the CRYPTOP_ENCODE operation

keybits

may be set to 0 if the key is encoded in a text format; otherwise it should specify the number of bytes in a binary-format key.

mode

should be set to one of the following to specify the hash function to use (default CRYPTO_MODE_SHA1):

cbsrc

the same as for other opcodes.

Example

++include ashinc:crypto.def

map1 text$,s,0,"The quick brown fox jumps over the lazy dog"

map1 key$,s,64,"key"

map1 hmac$,s,132

map1 status,i,4

! generate HMAC-SHA256 for text$ using key$

xcall CRYPTO, CRYPTOP_HMAC, status, text$, "", hmac$, "hex", &
CRYPF_NONE, CRYPTO_CIPHER_NA, key$, 0, CRYPTO_MODE_SHA256

? "hex encoded hmac-sha256: ";hmac$

New //SETTRANSFORM printing directive transforms the coordinate space to rotate, translate, shift and/or stretch the output. Syntax:

//SETTRANSFORM,m11,m12,m21,m22,dx,dy

where:

m11,m12,m21,m22 are floating point multipliers

dx,dy specify a reference point in twips (1440/inch)

The effect of the //SETTRANSFORM directive is to tranform every point (x1,y1) in the original coordinate space to a new point (x2,y2) based on the following formulas:

x2 = (x1 * m11) + (y1 * m21) + dx

y2 = (x1 * m12) + (y1 * m22) + dy

Note that the transformation is independent of SETMAPMODE and affects all subsequent output, with the exception of //METAFILE.    

Examples

//;mirror about horizontal axis at y=7920 (5.5" down)

//SETTRANSFORM, 1, 0, 0, -1, 0, 15840

//;mirror about vertical axis at x=6120 (4.25"over)

//SETTRANSFORM, -1, 0, 0, 1, 12240, 0

//;rotate 180 around point 4.25" over, 5.5" down (8.5x11 center)

//SETTRANSFORM, -1, 0, 0, -1, 12240, 15840

//;shrink horiz 25%, stretch vert 50%, shift down 1" and right .5"

//SETTRANSFORM, 0.75, 0, 0, 1.5, 720, 1440

Collections enhancement: writable iterators. You can now update the value of an element in a collection via direct assignment to the iterator. For example, the following foreach loop updates the value of each element by appending "-updated" to it:

dimx $foo, ordmapm(varstr;varstr)

...

foreach $$i in $foo()

    $$i += "-updated"

next $$i

Notes:

•   This technique works with all collection types (ORDMAP, ORDMAPM, MLIST).

•   In the case of ORDMAPM, it is the only way to change the value of an existing element for which there are duplicate keys.

•   In the case of ORDMAP, the direct assignment to the iterator in the above example would be equivalent to ...

$foo(.key($$i)) += "-updated"

     ... except much faster, since the key lookup, deletion, and re-addition steps are all eliminated.

•   In the case of MLIST, it eliminates the need for the .ref($$i) function, (which is now effectively deprecated).

•   The iterator is only writeable when it appears on the left side of the equals sign in an assignment statement. In all other cases, particularly when passing an iterator as an argument to a function, it remains read-only.

XTREE enhancement: new PopupMenu commands:

$CBSETX:  same as $CBSET but sets xtr'xvalidate bit &h08

$CBRSTX:  same as $CBRST but sets xtr'xvalidate bit &h08

$CBUNDOX:  same as $CBUNDO but sets xtr'xvalidate bit &h10

These new variations of the checkbox set, reset, and undo commands resolve a problem with the standard ones involving ambiguity over the possible interpretations of the xtr'validate = 3 that they return.

XTREE enhancement: Auto-Sum column footers. To create a footer that shows the column total and auto updates as cell values change, set the footer text to "=SUM". For example:

coldef += "20~10~Qty::=SUM~#E~~

coldef += "30~12~| Weight::| =SUM~#E~~

Note that as illustrated in the second example, the optional header/footer alignment code—"| " for centering—precedes the "=SUM". Typically is isn't necessary to specify an alignment code for the footer though, as the =SUM option will automatically use the same alignment as the column being summed.

Also note that the footer in question here appears at the bottom of the grid during display and editing operations, not to be confused with the Advanced Coldef Option "Footer=" which defines a page footer for printing.

XTREE enhancement: Automatically fill in a target cell based on the contents of a source cell using a lookup table. This is similar to the combo/list/substitution capability defined with ListX and CellListX and enabled by cformat "l" or "ll", except that the description appears in a separate column from the code—i.e., there is no need for a combo/dropdown box. Also, the list of code/description pairs is file-based rather than embedded in the coldef.

The feature is intended for data-entry cases where the user is entering codes for which you want to provide immediate visual confirmation by looking them up in a table and displaying the corresponding description. It fills the gap between small lists, where a combo box might make more sense, and very large or complex database lookups, where only an exit to the application would make sense. Between those two extremes, say lookup tables between 50 and 50 thousand entries, providing the table to XTREE once and letting it do the lookups internally will be much faster and more convenient; this is especially true in the ATE case where the turnaround time to exit and re-enter might be a significant fraction of a second, enough to slow the data-entry operation.

For example, in a tree used to key in general ledger transactions, you might use this technique to echo the account description in a non-editable column when the account code is entered.

Setup requires two new Advanced Coldef Options:

FileListX=idx,fspec

LookupX=idx,targetcol

FileListX defines the table and associates it with an single character index code in the range of A-Z or a-z. Note that the index shares the same space with the ListX and CellListX lists, so must be unique relative to them. In fact, combo and list substitution columns, i.e. cformat "l" or "ll", may refer to lists defined by FileListX just as they can for CellListX.

The fspec can be an AMOS or native spec from the client perspective. In the case of ATE, the search path will automatically include the %ATE%\Cache and %ATE%\PermCache directories, and it is up the application to transfer the file from the server if necessary.

Tip: you may want to use the Fn'FileAgeDiff() function in the FNFILEAGE.BSI module of the SOSLIB to determine when your FileListX file becomes out-of-date relative to the data file it was extracted from. For ATE, the ATEAPX.SBX routine will be handy for syncing the file to the client.

The file should be formatted as follows:

code,description

code,description

etc.

As with the List{X} and CellList{X} lists, if the first character of the first code is neither an alphabetic character or a numeric digit, it is assumed to be the delimiter; othewise the delimiter is assumed to be the comma. However, unlike the other lists types, here the descriptions may may be quoted if they contain the delimeter. So standard two-column CSV files should be acceptable.

To associate the list with a source and target column, add the LookupX= clause to the coldef entry for the source column—i.e. the column containing the code, specifying the index used in the FileListX definition, and the target column, which is where the description will be echoed.

The lookup and fill operation is performed automatically whenever the source column is edited and changed. If there is no match for the code, the description will be blank. When loading data into a tree, the lookup will be performed only if the target column is blank. Chances are that the application already knows the descriptions associated with the codes being loaded into the tree, so it is probably more efficient for it to specify them rather than force XTREE to look each one up.

Note that if you want the looked-up descriptions to be returned to the app with the answer array, use the "U" code for the description column.

XCALL SQL enhancement: SQLOP_FETCH_ROW now supports fetching a row into an ordmap:

dimx $rowmap, ordmap(varstr;varx)

...

cmdhdr.opflags = FETCHR_ROWMAP

xcall SQL, SQLOP_FETCH_ROW, cmdhdr, $rowmap()

foreach $$i in $rowmap()

    ? "Column name: ";.key($$i);", value: ";$$i

next $$i

Requirements / Comments

•   Requires libashmysql library 1.4.142+

•   Related opflags added to SQL.DEF:

•   If a column name is blank, possibly because it is an expression, a name will be generated of the form "expr-#" (1,2,3...)

•   The ordmap(varstr;varx) format will handle any field type. Text fields will appear as they are stored in the database. Numeric and other formatted field types will be converted to the standard display representation, the same as for the FETCHR_ROWSTR and FETCHR_ARRAY formats. BLOB fields will be encoded, and automatically decoded when assigned to a suitable variable type.

•   Reinstate support for the ashico1::xxx icons in APEX.CFG. Support had been dropped in 6.5.1617 when switching to the new *_i22b.png icons.

•   If the new icons are not found, it reverts to the old icons.

•   Installer now renames the old APEX.CFG to APEX.OLD before updating it.

•   The Preview Preferences button has been added back to the toolbar. It is also available from the main window Settings menu.

•   New spooler switch: SPSW_NOSAVESTATE (&h02000000) stops APEX from saving the user state on exit. This might be useful when preview unusual documents to avoid making any correspondingly unusual state adjustments (zoom, etc.) become the default for the next normal document.

New language feature: INPUT CSV into a dynamic array. Syntax:

DIMX ary(n), X, 0, auto_extend  

...

INPUT CSV #ch, ary()

The above syntax is equivalent to...

INPUT CSV #ch, ary(1), ary(2), ...

where the number of array elements specified is automatically adjusted at runtime to the number of fields on the line.

Requirements / Comments:

•   Compiler edit 854+

•   The ary() must be allocated with DIMX, and must be of type X. 

•   The array element size doesn't have to be 0 (i.e. dynamically sized), but if not, individual fields may be truncated as needed.

•   For auto_extend arrays (highly recommended), the extent will be set to the number of fields input, with 0 indicating none (probably EOF).

•   In the case of a non auto_extend array, any fields on the input line beyond the fixed extent of the array will be discarded.

See the SOSFUNC:FNCSVUTL.BSI module for an example of using INPUT CSV into an array to convert each line of a CSV file into an ordmap.

Redesign the runtime mechanism for passing parameters to subroutines, functions and procedures to accomplish multiple goals:

•   Eliminate the prior hard limit of 128 maximum parameters. The runtime system now has no limit; see below for compiler limits.

•   Reduce memory overhead for typical routines, especially in the case of highly nested functions.

•   Eliminate nearly all cases of internal subroutines that required a specific parameter to be passed as F,6, improving efficiency but especially flexibility (and eliminating a source of bugs for unsuspecting programmers.) Subroutines that previously required F,6 (or in some cases other F,4 or F,8) parameters that now allow any suitable numeric type: ACCEPN, COMMON, FLOCK, RENAME, SLEEP, ANYCN, DSPLY, MMENU, PRINT, RDATE, STENO, BLOCKS, CISAM, INFLD, LAPSED, MX_FINDNEXT, MX_ROUND, MX_USRIO, PRTCHK, SIZE, TCPX, ACCESS, DATES, SERCH, SBRC, BOX1C, DYNLIB.

XTREE enhancement: add Advanced Coldef Options:

•   LoadOptions=NoRowIf#

•   LoadOptions=NoRowIf!

These two options are similar in concept to the like-named ExportOptions (see 6.5.1626.0 below) except that they apply to the operation of loading data into the tree. The NoRowIf# option skips rows with a numeric value # 0, while NoRowIf! skips rows with a numeric value of 0. Typically the column is defined as a one character #, but could also be a checkbox.

The intended usage would be for a situation where you are repeatedly displaying items from a large array, but with varying filtering such that each iteration of the display may show different items from the set. Rather than have to maintain two separate arrays (one with all of the items and one with just those to display), you can just add a column to the array to indicate (with 0 or 1) whether to display the item.

Notes

•   Only supported with Array Mode (not file or CSV mode).

•   Only applies to opcodes XTROP_CREATE and XTROP_REPLACE.

•   Purely a client-side feature; no special support or version requirements   on the server side.

•   Removing items from a tree, by resetting the value of the LoadOptions column and then doing an XTROP_REPLACE, is similar to using XTROP_DELSEL, but the LoadOptions approach is somewhat more flexible (particularly in its reversibility), and probably easier to use.

•   In the ATE environment, using the LoadOptions technique to add or remove a small number of rows is particularly efficient due to optimization of the XTROP_REPLACE operation when only a few rows are changed.

•   See the sample program, TSTXFLTR2.BP[908,76] in the EXLIB for an example.

XTREE enhancements: new values for the ExportOptions Advanced Coldef Directive:

•   ExportOptions=No : Causes the associated column to be excluded from exporting. Applies to real columns only.

•   ExportOptions=Yes : Causes the associated column to be included in the export, regardless of whether the column is hidden in the display view. Note that hidden columns will be output according to their physical position in the coldef. Applies to real columns only.

•   ExportOptions=NoRowIf# : Causes the entire row to be excluded from the export if the value of the corresponding column is not zero (or in the case of a checkbox or radiobutton cell, is checked / set). This would typically be used with an editable checkbox column to select rows to include or exclude from the export. Applies to real columns only.

•   ExportOptions=NoRowIf! : Opposite of NoRowIf#, i.e. excludes the row from the export if the column value is zero (or unchecked).

•   ExportOptions=PhyOrder : Causes the order of the columns in the export to be based on the physical order they are defined in the coldef, rather than the display order (which is otherwise the default). (This option affects all columns, regardless of the column that it is specified with. Also note that the the option can be abbreviated to ExportOptions=Phy; any additional characters are ignored.

XTREE export enhancement: you may now export directly to XLS rather than tab or comma delimited, using the new PopupMenu system command:

$EXPCSV2XL{:inispec}

$EXPCSV2XL is like $EXPCSV except that after creating the CSV file (which is named %TEMP%\XTREE##.CSV where ## is the job number), it calls CSV2XL.SBX to convert it to XLS. If no inispec is specified, the default INI file for CSV2XL will be XTRCSV2XL.INI (with the search patch consisting of the current ppn, [p,0], and BAS:. If no XTRCSV2XL.INI is found in any of those locations, is uses the standard BAS:CSV2XL.INI file.

If the inispec is specified (AMOS or native format, may include %ENV% vars) then is uses that filespec without any search path.

Unlike the $EXPCSV and $EXPTSV options, there is no "+" variation to open the file after creating it. Instead, this is determined by the CSV2XL initialization file Launch option.

As with the other export options, you can enable it globally by adding:

SBR=XTREE_EXPCSV2XL

to the MIAME.INI. In the case, there is no option for the INI file, which will always be the XTRCSV2XL.INI, using the search patch specified above.

Compiler (edit 847) bug fixes related to indirect/lblref functions:

•   Indirect procedures are now supported as well as functions. Previously, attempts to use indirect procedures may have resulting in undefined reference compiler errors.

•   Indirect functions/procedures, , i.e. LBLREF parameters, can now be passed by name, as expected. The actual function name being passed must be prefixed by the "@", just as it would when using standard ordered parameters. The parameter name can optionally be prefixed with @". 

For example, assuming a function defined as:

Function Fn'Foo(@callback() as lblref) ...

any of the following syntaxes is supported:

call Fn'Foo(@callback=@Bar())  ! @name=@routine

call Fn'Foo(callback=@Bar())     ! name=@routine

call Fn'Foo(@Bar())            ! @routine (ordered param)

•   In the absence of an explicit "as s#" clause, string arguments to functions and procedures, as well as the return value of a string function, now defaults to s0 (i.e. dynamic, unlimited) instead of the current STRSIZ.

•   STRSIZ 0 now sets the default string size to dynamic, as would be expected. Previously it set the default string size to a fixed length of zero, i.e.  making it impossible for any unmapped string variable to hold a value.

•   SWITCH and CASE arguments are no longer limited by the current STRSIZ. Previously the compiler would complain about it you were forced to actually change the STRSIZ to accommodate them, which was not very programmer-friendly.

Note that all of the above are purely compiler adjustments, i.e. they change the resulting RUN programs, which are backward compatible as least as far back as 6.0.

Runtime enhancement to support new .CLEAR ARY() options:

•   For traditional MAPped arrays, as well as for DIMX arrays without the AUTO_EXTEND attribute, .CLEAR ARY() simply clears the contents of the array without affecting its structure. This applies to both single and multi-dimensioned arrays. The end result is exactly equivalent to iterating through all of the array elements and setting each to null except that it is easier to code and faster to execute.

•   For DIMX arrays with the AUTO_EXTEND attribute, the extent of the first dimension of the array is reset to 0. This is similar to resizing the array to 0 using REDIMX except that the array remains defined and ready to receive new elements (via auto-extension). Note that for multi-dimensional arrays, dimensions beyond the first retain their original extents; this is necessary for re-using the array since only the first dimension is subject to auto-extension.

Compiler edit 844 and runtime enhancement: Collections can now be passed by reference in an XCALL to an SBX. On the calling side, the syntax is the same as for passing a DIMX array of structures, i.e. just specify the collection name with an empty set of parentheses, e.g.

dimx $coll, ordmap(varstr;varstr)

...

xcall MYSBX, $coll(), ...

The receiving side is also similar to that for receiving a DIMX array of structures, i.e. you must first declare the receiving array with a variation of the DIMX statement including the BYREF clause, e.g.

dimx $locoll, ordmap(varstr;varstr), byref

Then use XGETARG or XGETARGS to receive the collection...

xgetargs $locoll(), ...

or

xgetarg 2,$locoll()

See the new MAPDIR.SBX and associated TSTMAPDIR.BP test program in [907,45] of the SOSLIB for a useful working example.

New parameter type ">" may be used to identify an indirect output string parameter, i.e. one that the underlying function treats as the pointer to the actual output, rather than the output itself. For example, in the following C function, the output parameter pstring will actually receive the address of the output string:

void getstring(char **pstring);

To call such a function with DYNLIB, you would use the following method:

map1 buffer,s,0            ! dynamic ok, or size sufficient for output

dlctl.opcode = DCOP_CALL

xcall DYNLIB, dlctl, "getstring(>)v", buffer

The ">" parameter code will cause DYNLIB to copy the actual output string to the buffer parameter rather than copying its address.

Warning: this feature is dangerous in that has to trust both the signature and the underlying library routine to output a valid address pointer; any discrepancy will likely cause a segmentation fault!

New opcode DCOP_DEREF (4) "dereferences" a pointer to return the value pointed to. Using the getstring() function in the previous example, if it was called with the parameter signature "p" instead of ">", to get the address directly, you could then get the value as follows:

map1 buffer,s,0

map2 address,b,4

dlctl.opcode = DCOP_CALL

xcall DYNLIB, dlctl, "getstring(p)v", address   ! get ptr into address

dlctl.opcode = DCOP_DEREF

xcall DYNLIB, dlctl, address, buffer  ! copy string pointed to by address

                                      ! into buffer

This can be useful in dealing with functions that return a structure containing pointers to strings, rather than the strings themselves. But any time you are dealing with direct pointers like this, you run the risk of a segmentation fault if there is any discrepancy between the expected and actual parameters or behavior of the underlying function.

The string containing the argument list was previously used in place, but since the area is within the terminal system output buffer, it was subject to possible corruption by other functions that use the output system. This could have interfered with the operation of XGETARG(S). For example, in the following SBX code, the second XGETARG might have returned incorrect information due to potential sharing of the same buffer space with DEBUG.PRINT:

XGETARG 1,ARG1

DEBUG.PRINT "ARG1 = "+ARG1

XGETARG 2,ARG2

This patch eliminates the danger of such a conflict.

Compiler enhancement (edit 838): new statement DEFALIAS allows aliases to be defined for the names of functions and procedures:

DEFALIAS <routine-alias>() = <real-routine>()

This can be a useful code management technique for isolating lower level changes or variations in routines—due to differences in versions, implementation, etc.—from the higher level application. For example, an application may have many different discount calculation routines based on the type of discount, some of which might be effectively the same. Rather than forcing the higher level code to know which discounts are effectively the same, or forcing you to maintain redundant routines which differ only by name, you can use DEFALIAS to create aliases. For example, the following statement would cause any subsequent references to the function Fn'Senior'Discount(qty,gender) to be converted into references to the function Fn'AARP'Discount(qty,gender):

DEFALIAS Fn'Senior'Discount() = Fn'AARP'Discount()

Notes:

•   Currently this applies only to functions and procedures and not subroutines

•   The empty set of parentheses is mandatory for both the alias and the real routine name. Currently the alias only affects the name; the arguments are passed through without change.

•   This is purely a compiler-level mechanism and does not require any runtime support—i.e. IT is backward compatible to all runtimes.

New optional parameter sockary is used to manage an array of sockets. When specified, the syntax becomes:

xcall TCPX, opcode, status, buffer, sockidx, flags, timer, hostname, sockary(1)

Argument 4 (normally sockport) is now interpreted as the index into the sockary, rather than the socket itself. As in the normal case, the TCPOP_ACCEPT calls expects the 4th argument to be the port to listen on.

The sockary() parameter should be an array of up to 1025 ST_SOCKARY structures, defined (in SOSFUNC:FNTCPXARY.BSI) as:

defstruct ST_SOCKARY

    map2 socket,b,3    ! socket value

    map2 ready,b,1     ! TCPOP_CHECK sets this to 255 if ready

endstruct

The last element of this array must be zero; this is how TCPX identifies the end of the array. In most cases an application would have no need to access this array directly. If you do want to access it directly, you should. Instead, use the utility functions in use the utility functions in SOSFUNC:FNTCPXARY.BSI to provide isolation from possible changes in the structure.

The main advantage of using the sockary method is that it by setting the sockidx parameter to 0, TCPX will perform certain operations (mainly TCPOP_CHECK and TCPOP_CLOSE) on the entire set of open sockets in the array, rather than just one socket at a time.

For TCPOP_CHECK, if sockidx is zero, TCPX will wait on all of open sockets until one of them is ready to read from, subject to the time limit set by the timer parameter. If there is a socket ready, it will return sockidx set to the index into the array for that socket, so that a subsequent TCPOP_READ will read from that socket. If multiple sockets are ready to read from, TCPX will use a round-robin scheme so as to not unduly favor those sockets near the start of the array. It will also return the status parameter set to the number of sockets that are ready, allowing the application (optionally) to read from them all by scanning sockary() for those with the ready flag set. This may or may not be preferable to just calling TCPOP_CHECK again and relying on it to return the sockidx of the next ready socket.

For TCPOP_CLOSE, if sockidx is zero, TCPX will close all of the open sockets, and return status set to the number that were closed.

For TCPOP_READ, if sockidx is zero, it will read from whichever socket is available, although this is probably not useful except in very particular cases.

Add to XTREE new Advanced Coldef Options:

ExportOptions=<options>

where <options> is a comma-delimited list of options related to the export function. It has two defined options:

•   Code: applies to ListX or CellListX columns, causing the code rather than the description to be exported to the CSV

•   Descr (default): export the description rather than the code.

As with most other Advanced Coldef Options it can be associated with a zero-column in order to make it the default for all other columns.

Language enhancement, compiler edit 828: Expand XPUTARG @argname mechanism (see 1607.0) to work for SBXs. This is similar to the XPUTARG @argname enhancement for functions (edit 825, 6.5.1607). Except that while that enhancement used the function or procedure definition to associate argument names with their ordinal numbers, this one uses the combination of previously seen XGETARGS, XGETARG and XGETARGSBX statements.

To avoid the potential for misunderstandings or ambiguity, the use of the XPUTARG @argname syntax will only be supported if there is a perfect one-to-one relationship between argument names and ordinal numbers, based on the XGETARG* statements seen previously at compile time. In other words, if one argument variable is retrieved from different argument numbers in separate XGETARG* statements, or one argument number is retrieved into multiple variables, the XPUTARG @argname syntax will generate an "undefined or ambiguous argument" error.

Language enhancement, compiler edit 825: XPUTARG now supports the ability to reference the parameter to be returned by its name rather than by its number, using the following syntax:

XPUTARG @arg {=<expr>}

where arg must be one of the arguments in the function's (or procedure's) formal parameter list. When identifying the parameter this way, <expr> becomes optional, defaulting to the parameter's current value.

Identifying the parameters by their names has two advantages over using the parameter numbers: 1) it makes for more self-documenting code, and 2) it eliminates the need to adjust the XPUTARG statements if you add, delete, or rearrange the function parameters, thus eliminating a source of bugs.

For example:

function fn'foo(arg1 as f6, arg2 as b4) as i2

    ...

    xputarg @arg1           ! new: same as xputarg 1, arg1

    xputarg @arg2=arg1*7    ! new: same as xputarg 2, arg1*7

    xputarg arg2,arg1*7     ! old: value of arg2 is arg # to return

    xputarg 2, -1           ! old: return -1 for 2nd arg

endfunction

Note the difference between the second and third XPUTARG statements above (with and without the '@'). In the former, we pass the value arg1*7 back for the argument whose name is arg2 (the second argument). In the latter, we evaluate arg2 and use that as the argument number to pass the arg1*7 value back to.

Compiler edit 822 language enhancement adds new shortcut operators:

VAR |= expr    ! equivalent to VAR = VAR or (expr)

VAR &= expr    ! equivalent to VAR = VAR and (expr)

Similar to the existing combo operations (+=,-=,*=,/=), these are just syntactic shortcuts to simplify common statements, in this case, those involving setting and clearing bits in a flags variable. For example:

To set specified bits:

FLAGS |= XTF_MODELESS           ! FLAGS = FLAGS or XTF_MODELESS

FLAGS |= XTF_LEFT or XTF_RIGHT  ! FLAGS = FLAGS or (XTF_LEFT or XTF_RIGHT)

To clear all but specified bits:

FLAGS &= XTF_MODELESS           ! FLAGS = FLAGS and XTF_MODELESS

To clear specified bits:

FLAGS &= NOT XTF_MODELESS       ! FLAGS = FLAGS and not XTF_MODELESS

Notes:

•   As with the other combo operations, these are transplants from the C language.

•   When setting / clearing bits in a flags variable, it is almost always better to use the bitwise operators (AND,OR) instead of the arithmetic operators (+-), since the former are idempotent (i.e. can be used redundantly without changing the result).

•   This is purely a compiler enhancement and has no effect on runtime compatibility for the compiled programs. So you may want to use this version of the compiler even if continuing to use the 6.4 runtime.

XTREE enhancement: new Advanced Coldef Options for radio/checkbox state-specific background colors:

RGBbg0=r,g,b

RGBbg1=r,g,b

RGBbg2=r,g,b

These act similarly to other RGBbg* options, except here they only affect radio buttons and checkboxes, causing the specified background color to be applied according to the state of the cell (0=cleared, 1=set, 2=indeterminate).

Notes:

•   The effect is immediate; there is no need to exit / reload the tree.

•   It only applies to cells that have a visible checkbox or radio button.

•   It applies equally whether the cell is enabled or disabled.

•   Unlike the generic RGBbg= clause, there is no optional index parameter.

•   When combined with other RGBbg clauses that affect the same column, the new state-specific versions take precedence. For example, if a checkbox column has the options RGBbg=200,200,200~RGBbg1=255,200,200~, then the cells containing a checkmark (state=1) will get the RGBbg1 value, while all the other cells (clear, indeterminate, or no checkbox) will use the standard RGBbg value.

See EXLIB [908,21] sample program XTRA6 for an example.

Beginning with compiler edit 821, a DEFSTRUCT may now include a MAP1 statement as the first member of the structure. The result is equivalent to the combination of the DEFSTRUCT without the MAP1 and the ontained MAP statements (including the MAP1) without the DEFSTRUCT. This is useful when migrating legacy code from traditional MAP1-style structures to DEFSTRUCT-style structures, eliminating the need to either convert them all at once or to maintain parallel versions of the structure layouts.

Eliminating the need to maintain parallel copies of mapped structure layouts was, after all, one of the primary motivations for the DEFSTRUCT concept in the first place.

For example, say you have a common include file with this record layout:

MAP1 CUST                    ! mapped customer record

    MAP2 ID,S,8

    MAP2 NAME,S,30

    ...

The equivalent structure definition and mapped instance would be:

    DEFSTRUCT ST_CUST        ! customer structure

        MAP2 ID,S,8

        MAP2 NAME,S,30

        ...

    ENDSTRUCT

    MAP1 CUST,ST_CUST        ! mapped instance of customer structure

The only problem with the above is that all existing references any of the members of the CUST record would need to be converted (e.g. from ID to CUST.ID, etc.) If you didn't want to go through all your programs at once, you instead could leave the traditionally mapped CUST record intact and rename the new structure version, i.e:

DEFSTRUCT ST_CUST            ! customer structure

    MAP2 ID,S,8

    MAP2 NAME,S,30

    ...

ENDSTRUCT

MAP1 SCUST,ST_CUST           ! mapped instance of customer structure

Now you would have two equivalent record layouts, CUST (ID, NAME, ...) SCUST (SCUST.ID, SCUST.NAME, ...). The main problem with that, aside from the resulting lack of syntax consistancy, is that if you modify the layout, you have to remember to modify both versions (the MAP1 CUST version and the DEFSTRUCT ST_CUST version).

This new compiler enhancement eliminates that problem by using a single set of MAP statements to generate both the structure definition and the traditional mapped variable definition, i.e.

DEFSTRUCT ST_CUST

    MAP1 CUST

    MAP2 ID,S,8

    MAP2 NAME,S,30

            ...

    ENDSTRUCT

    MAP1 SCUST,ST_CUST       ! mapped instance of customer structure

Now the traditional record variable CUST and the new structure version SCUST are guaranteed to always have identical formats.

Note that this is purely a compiler enhancement and has no effect on runtime compatibility for the compiled programs. So you may want to use this version of the compiler even if continuing to use the 6.4 runtime.

XTREE drag-drop multi-level enhancement: when dragging a parent item whose children are all collapsed, the entire set (parent + children) is now dragged as a single unit. Previously the hierarchical levels were ignored and each item was dragged irrespective of its level.

Note the following:

•   This only applies when the children are collapsed (not visible). If they are expanded (visible), then the behavior reverts to ignoring the levels and treating each item independently.

•   Even though the parent/child group may be moved as a unit, depending on where it is dropped, it may still disrupt and/or merge with existing parent/child groups. For example, if the parent is dropped between two children of another group, the target parent/child group will be split, with the children above the drop point remaining with their prior parent, and the children below the drop point joining the parent/child group being dropped. (The question of whether to limit the legal drop points to avoid this kind of side-effect is under review.)

•   Moving a parent/child group does not affect their absolute levels in the hierarchy. An item at level x will remain at level x, regardless of where it is moved to. In other words, a parent cannot be converted into a child of another parent via drag-drop. The application could implement such an effect though, by detecting the drop via the Advanced Coldef Option DropExit=###, using the SELECTION and ORG'ROW fields in the answer array to identify the items that were moved and where they were moved to, and adjusting the level fields up or down before re-entering the tree with XTROP_REPLACE.

•   There is currently no Undo operation for drag-drop—although again, the application could implement this by reloading the tree contents from a previously saved copy of the data array.

Developers are therefore urged to exercise caution when implementing drag-drop, especially in conjunction with multi-level trees.

XTREE drag-drop multi-select enhancement: XTF_MSEL and XTF_DRAGDROP may now be combined, allowing the user to select and drag multiple items at a time.

Notes:

•   As in the single-select, multi-level case, if a parent item with collapsed children is dragged, then all of its children are dragged along with the parent. All of the warnings listed above for the single-select multi-level case apply here as well, the possibilities for chaos becoming more exacerbated by the possibility of dragging a heterogenous collection of individual and multi-level items in one operation.

•   Non-contiguous items may be dragged as a group; they become contiguous at the drop point.

XTREE enhancement: XTF2_ANSEQDATA may now be used with XTF_MSEL and/or XTF_DRAGDROP. This requires that the data array elements start with the special SELECTION, and if applicable, ORG'ROW, fields as would be required in the answer array (see XTF_DRAGDROP topic for details). The remaining fields in each data array element can be laid out in any order, as is normally the case with the data array and with XTF2_ANSEQDATA. The following examples may help clarify this:

defstruct ST_XTDATA_AM    ! data elements with ANSEQDATA and MSEL

    map2 SELECTION,S,1    ! (mandatory) selection flag

    <remaining fields in any order>

endstruct

defstruct ST_XTDATA_AD    ! data elements with ANSEQDATA, DRAGDROP

    map2 ORG'ROW,S,4      ! (mandatory) drag/drop cross reference

    map2 SELECTION,S,1    ! (mandatory) selection flag

    <remaining fields in any order>

endstruct

The layout requirements for the combination of multi-select and drag-drop is the same as for drag-drop alone.

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