******************************************************************************* SHARP APL for UNIX version 6.0.0 README File Copyright 2000 Soliton Associates September 2000 ******************************************************************************* Company Information =================== Soliton Associates Limited 44 Victoria Street Suite 2100 Toronto, Ontario, Canada M5C 1Y2 Business Phone: 416-364-9355 FAX Phone: 416-364-6159 Technical Support / Customer Support ==================================== INTERNET: www.soliton.com E-MAIL: support@Soliton.com ******************************************************************************* This file provides important information not included in the SHARP APL for UNIX library of documentation. If you don't find what you are looking for, you might find it in the file, which contains information on previous releases of SHARP APL for UNIX. CONVENTIONS IN THIS FILE: Because APL characters are not reproducible here, APL symbols are translated to ASCII strings such as "{iota}" and # represents the system QUAD function. This translation allows APL statements to be "read" as their APL character counterparts. UNIX file names and commands, within text are set apart with <>. README FILE CONTENTS: 1. Changes to the upgrade process 2. System Configuration and Logging 3. Interpreter 4. Primitive Functions and Operators 5. System Functions and Variables 6. Intrinsic Functions 7. Shared Variable Processor 8. Network Shared Variable Processor 9. File System 10. Linux 11. Miscellaneous ******************************************************************************* SHARP APL for UNIX version 6.0.0 has a common source code base and supports a new, non-kernel Shared Variable Processor (SVP) driver which is 100% functionally identical to the older, kernel version. SAX 6.0.0 completes a significant effort to improve portability and maintainability. 1. Changes to the upgrade process - SHARP APL for UNIX release distributions, software and documentation, are now provided on CD-ROM. - It is no longer necessary to stop the Volume Manager on a Solaris system. The routine to do this has been removed from the script. - Previously the Upgrade script prompted for the directory to use as the repository for scripts. It now more clearly states it is the repository for customization files. - Previously only some exits from the script were trapped. Now all exits are trapped. 2. System Configuration and Logging - The state indicator stack is now logged to $SAXLOG on abnormal termination. This provides additional diagnostic information. - "unexpected svp error" message is now logged to $SAXLOG as well as being displayed at the console. - LIBLOG library - a new error code has been introduced to prevent process termination when a trace control file is not found. The severity of this error is "warning". This previously produced an APL "file access error". - The message "Undefined APL_TRACE variable" has been changed to "Tracing is turned off". - The sami.script and nsvp.script scripts now recognize the environmental variable APL_TRACE. If it is undefined, the default is used - $SAXDIR/trc. - When you need more information regarding a problem with your SHARP APL system, you can turn on tracing. Usually you will only do this when requested by the Soliton Support staff. You can set up tracing for processes , , , and . To trace one of these - Copy the appropriate file from $SAXDIR/etc into $SAXDIR/trc, where is the name of the process you wish to trace. In this copy (<$SAXDIR/trc/xxxx.trc.ctl>), turn the trace macros on for the requested information by editing the appropriate occurences of OFF to ON. Define the environmental variable APL_TRACE to be $SAXDIR/trc. When you start SAX after all this has been completed, you should find a file in the $SAXDIR/trc directory. 3. Interpreter - The SAX 6.0.0 APL interpreter contains many internal changes, as the result of a significant engineering effort aimed at improving performance, maintainability and portability. Users are requested to pay special attention to testing of existing applications. Any behavioral differences between SAX 6.0.0 and earlier SAX releases should be reported to . - Substantial changes have been made to the interpreter. These changes required that some internal representation of the workspace also be modified and the workspace version number has been incremented. All workspaces are affected. When being loaded for the first time, the message "obsolete ws representation" is displayed. )xload and )save the workspace to increment the workspace version number. This action is also required for all public library workspaces shipped by Soliton. - After sending attention to an s-task, the interpreter no longer ignores certain system commands (including )vars, )fns, )lib, and )libs) until an APL expression is sent for evaluation. - Entry of out-of-range numbers (for example 3e308) was leaving unreferenced objects in the workspace. This has been corrected. - A deficient algorithm used to calculate the factorial float number has been improved. The previous limit in the near zero domain allowing negative numbers no greater than -9.9999...99e-16 has been corrected. - Previously a function could not have the same name for its argument(s) and some function labels. This is no longer the case. - Sunview is no longer supported by AP124. - The mechanism for saving a workspace has been changed to eliminate a race condition between generating the file name and creating the file. The lock on the destination workspace file has been made non-blocking. If a task fails to acquire the lock, it gives up and logs the event. This has a couple of implications: - in a ttask, )save can fail and produce the error message "ws access error" for this temporary situation. - the workspace that is left after multiple tasks write to the same crash workspace may not be the one from the 'last task'. 4. Primitive Functions and Operators - Idioms - The parser now recognizes and uses special codes for: 1 {take} {rho}{rho} ''{rho} {iota} 0 1 {drop} 0 {rho} {neg}1 {take} {neg}1 {drop} <{rank} 0 <{rank} 1 <{rank} {neg}1 <{rank} 2 <{rank}{eng} 2 ,{under}> - The following, as described in "A Dictionary of APL", are now implemented in SHARP APL for UNIX. Refer to the "Language Guide" in the SHARP APL Documentation Suite for more information. Indirect Assignment ply all - For statements in which a variable forming the left operand of became defined in the statement, and the derived reduce-function acted on an argument returned from {iota}, the reduce-iota idiom was executed twice. For example, b <- 'a' & b , a/{iota}{rho}a <- 'q'=b <- b,'a' aaa A "solution" was released in version 4.9.0 in which the correct answer was returned, but the /{iota} idiom was not used in this case. This caused workspace full and slower execution where not warranted. Now, the parser makes note of assignments in a statement. - A new, fast hashing method has been introduced for non-zero {cut} with a character vector. The new method reduces storage size of the result. More storage is required to execute, but there is up to a 10% speed up for larger objects. - Nonce error was being returned for dyadic {cut} with an all zero left argument. This is no longer the case. - Scalar primitive function reduction of some empty arrays returned an empty result when the function had no identity element. A domain error is now signaled in these cases. - When both arguments are character and ranks are less than 3, {iota-underbar} returned a faulty result due to a search beyond the rank of the left argument. This has been corrected. - The characters @ and & are synonyms for { and }, respectively. Either notation can be used. The interpreter tests the value of the environmental variable SAXBRACELOG at start-up. If the variable exists and is non-zero, occurences of { and } cause a 4 line message to be written to $SAXLOG. The entry consists of a description of the event ( left or right brace found ), the workspace name, and the top two elements of the stack. The stack elements are described by the function name or description of stack element type (immediate execution, #trap, etc.) and, in the case of a function, the statement number in the function (as opposed to the line number). 5. System Functions and Variables - Support for the euro currency symbol, including the glyph has been added (position 178 #av and 217 #avm). - Total CPU was not being recorded in #MF records. Now, the first row/second column contains the cpu usage for the function, excluding calls to user-defined functions. The documentation notes that the statistics reported for the header (the first line of the table) show resource totals for all lines being monitored. The total is maintained separately from the line totals, and can be different than the sum of the line totals. The reason is that each function has a line 0, the resources for which are not recorded elsewhere in the #MF report. - #bind is a system function with monadic and dyadic use. It was originally the function called 'IFbind' which still exists in workspace <1 if>. * monadic use #bind 'func' 0 #bind 'math' 2 * dyadic case (principal use of #bind) 'unix.getuid' #bind 'getu' 2 - With #pp set to 1, {thorn} was returning garbage after the decimal point in exponential format results. This has been corrected. - In #parse, only syntax and nonce errors found while parsing a statement resulted in a 'failed' result. All errors found while parsing a statement are now reported. - An initial #sp value, as provided with the -s flag on start up of SAX returned, upon <)load> or <)clear> after setting #sp, to an empty vector. #sp now retains the empty vector in this situation. - #run could fail when given an account number and password. Most frequently, this would happen on a Linux system with the shell. We have added to to correct this problem. 6. Intrinsic Functions - System V Semaphore, Message Queue, and Shared Memory intrinsics are now available as part of the Sunix intrinsics group. See complete documentation in the "Intrinsic Functions Manual" included in the Documentation Suite. - initgroups() has been added to the Sunix group - The intrinsic has been added to the Socket group. It allows a process to ignore SIGPIPE, return to default SAX handling of SIGPIPE, or to inquire which is the current handler. Refer to in the workspace <1 socket> or the "Intrinsic Function Manual" in the Documentation Suite for more information. - There is a change in behavior of the intrinsic due to the new SVP. The new behavior is more efficient in that no unnecessary posting is done. Old Behavior: post everyone, regarding changes in state following the use of the intrinsic. New Behavior: post only those that have requested to be posted with certain types of changes by issuing the intrinsic before the . 7. Shared Variable Processor - A new, non-kernel, Shared Variable Processor (SVP)is the default in SAX 6.0.0. This re-engineering means the SVP is no longer a device driver which runs in the Unix kernel space. All APL tasks now use a piece of shared memory buffer to share variables. This is a co-operative model in contrast to the old centralized model. - The old SVP is still available. If you experience difficulties with the new SVP, please contact support@soliton.com for assistance and, if necessary, directions to back off to the old SVP. - If the SVP is up and running normally, "svpdump -site" or "svpdump - ver" will report meaningful information. - SVP no-reconnect feature is now available to APL. A retract, followed by a new offer, could happen so quickly that the AP side missed it - and thus a new offer could receive data intended for the previous partner. 'No reconnect' is an attribute of one or both sides of a share, specified by one side or the other when an offer is made. If no reconnect is set, there are 2 consequences: 1/ No existing offer created by retract (whether or not it has no-reconnect set itself) will match the new offer. 2/ If, after coupling goes to 2, the partner retracts, the resulting offer will never be rematched under any circumstances. A tilde ("~") can now appear as the first character of either name in the argument to #svo. That is - (whatever) #svo '~xname' or (whatever) #svo 'iname ~xname' or (whatever) #svo '~iname xname' If the tilde is present, there are 2 changes. The first is that no-reconnect will be in effect for this offer (1 and 2 above). The second is that the result will have another possible value - it will be {neg}1 for any variable which has the tilde and whose offer is in state (2) above. The {neg}1 value will replace the value "1" which is currently returned in this situation. For a retracted no-reconnect share, both monadic and dyadic #svo will return {neg}1, but only if a tilde is specified. #svo '~aaa' returns {neg}1 #svo 'aaa' still returns 1 for compatibility reasons 8. Network Shared Variable Processor - On Solaris, host name resolution was insufficient. Some remote signons were refused. This is no longer the case. 9. File System - The SHARP APL file system server, Fileserver (FS3), is a file management system that runs independently of the interpreter, acting as a transparent broker between the UNIX file system and the conventional SHARP APL component file system. There are currently 3 file systems - FS1 the Native File System FS2 the Semaphore File System FS3 the File Server - FS3 can work with NFS with some limitations. Depending on what sort of privilege is granted by a NFS server to a client with regard to superuser access, FS3 may not be able to perform certain, low level file system operations such as file synching, file deletion, directory entry, unlinking, etc. - FS3, FS2, and FS1 all use the same physical files. In some unusual circumstances, the header portion of a component file might have been damaged by FS2 or FS1. Such damage may be discovered by running the utility program with the -v option. If reports that file ties are set when the file is off-line, the header has been damaged. Make a backup copy of the damaged file, and then run on the damaged file. Run on the sifted file to make sure the damage has been repaired. Another instance of this would be a corrupted component file (probably caused by a crash of some sort) which reports a "file tied error" when attempting to tie the file using the file server. This happens because a crashed component file usually has some stray ties left around. This can be confirmed by running the utility on the file. The following is an example of a procedure which could be used - cmpfile.sf has stray ties, probably due to a previous crash fsutil -s shut down the file server tiers cmpfile.sf confirms the stray ties mv cmpfile.sf cmpfile.sf.bad rename it cp cmpfile.sf.bad cmpfile.sf physically copy it back sift cmpfile.sf compress it cfcheck -v cmpfile.sf verify it NOTE: copying the corrupted file is a key step. Essentially, it assigns a new Unix inode number to the copied file which will not be found in the corrupted list of tiers. - Mixing FS3 with FS1 or FS2 is permissible, but NOT RECOMMENDED. Any file tied by FS1 or FS2 cannot be, at the same time, tied by FS3. - By default, a session is attached to the conventional file system. To make sure you are using FS3 exclusively, set the environment variable APLPARMS="usefilelocks=3" or edit the apd*.tab files in your $SAXDIR/etc directory to start SAX using -Yusefilelocks=3. If you do not take these measures, some sub-tasks may be using FS1 instead of FS3 and that would cause some unpleasant conflicts. NOTE: does not reference APLPARMS. You must edit it to include the -Yusefilelocks=3 start parameter in the SAX start up line. - Known problems with FS3: Under some obscure conditions, the copy of the access matrix of a file in memory is not synchronized to the access matrix stored with the file on disk. This means that the access matrix of a tied file is not honored by the interpreter. This problem cannot be reliably reproduced, so has not been fixed. We added some tracing so that the states of the file server are logged to sax.log when this problem occurs. We hope that the extra logging might bring us more information as to when and how this bug occurs. When FS3 is under severe load (many clients issuing lots of file requests), some clients don't get their fair share of service responses (classified as the bounded waiting time problem). Some design changes have been made to FS3 to reduce the probability of this problem. 10. Linux - The dynamically linked version of SAX/L can only run on Linux systems with libc-2.0.7.so and libncurses.so.4.2 or higher. If you do not have these libraries installed on your Linux system, you will have to run the statically linked executable of the SHARAP APL interpreter by setting the environment variable APLPATH=$SAXDIR/bin/stapl. $SAXDIR must be the directory in which you installed SAX. - SAX supports NIS based passwords, clear (non encrypted) passwords, and shadow (DES encrypted) passwords. It does not support MD5 signature of passwords. SAX will run with MD5 passwords enabled, however #run 'userid:pass ...' will fail. - Performance improvements in SAX/L can be acheived by changing the value of the start-up option from it's default value of 2 to 0. You can use the environment variable APLPARMS, setting it directly in UNIX, or indirectly in your SAXRC file. For more information on this refer to the SHARP APL for UNIX documentation. In the Handbook, the section "Starting an APL Session" ("Suite Yourself" Options) contains a description of the parameter. The section "Setting Up Your Environment" contains details of the SAX start-up settings. The "Intrinsic Functions Manual" secion on unix.filesync contains an explanation of file syncing. 11. Miscellaneous - An international keyboard and font support can be found on in the directory $SAXDIR/xmpls/tools. This keyboard may not be appropriate for all users. Please read the MESSAGE in that directory and Keymap.txt. If you have any questions about these changes or would like more information contact .