Wednesday December 26, 2001 dL4 For Unix Runtime 4.4.1 Maintenance Release All Rights Reserved. Copyright (c) 1994 - 2001 by: Dynamic Concepts, Inc. Aliso Viejo, CA 92656 USA Email address: techsupport@dynamic.com Information: www.unibasic.com Downloads: ftp.dynamic.com Pre-installation instructions ============================= o This release requires an SSN authorized for release 4 of dL4. Without such an SSN, dL4 can only be used in single user demo mode. o Problem reports should be emailed to techsupport@dynamic.com. All problem reports should contain a description of the problem, the operating system name/revision, and, if at all possible, a reproducible sequence Installation instructions ========================= 1. Ensure that you have Passport version 3.1 or greater installed on your system. For common platforms, the latest Passport software can be obtained from www.unibasic.com or ftp.dynamic.com. 2. Login as 'root'. 3. If upgrading an existing dL4 installation, make certain that all dL4 scope and run users have exited dL4. If a program cache is used (see the dL4 Installation and Configuration Guide), delete any existing cache using the Unix ipcs and ipcrm utilities. 4. Copy the distribution file to any temporary directory on your system, e.g. "/tmp". 5. If the distribution file has a ".Z" extension, uncompress the file using the command "uncompress filename.Z". If the file has an extension of ".z", rename the file with an uppercase "Z" before uncompressing the file. 6. Unpack the distribution file using the command "cpio -imcduv 2gb) format pgmcache Utility to display or delete the program cache query Utility to display file characteristics term Utility to monitor or terminate ports verindex Utility to validate Portable or Universal Indexed-Contiguous files. Highlights of This Release ========================== o An optional separate buffer for WCQUERY results to simplify GUI programming. o Support for character attributes such as reverse video in windows on terminals where changing attributes uses a visible space on the screen. Such terminals include the Wyse 50, Televideo 925, and emulations of those terminals. o A new option to simulate character attributes as a visible space on any terminal. o Support for sending commands to a dL4Term client to execute local Windows programs. o Support for opening a local printer on a dL4Term client on a channel. o CALL WHOLOCK() to determine what port has locked a specific record. o A DATEUSING$() intrinsic function to format dates. o Extensions to improve compatibility with other IRIS compatible Business BASIC languages. dL4 and dL4Term =============== o Some of the new features of dL4 4.4.1 are supported only when using dL4 with the dL4Term 4.4 telnet client. dL4Term is a separately available and licensed product. Please contact the Dynamic Concepts Sales department for information on obtaining a copy of dL4Term 4.4. New in This Release ================================================================================ Dec 26 2001 (Release 4.4.1) o Fix bug: the 'IOBI' and 'IOBC' mnemonics did not work correctly with a dL4Term client. o Fix bug: the CALL RENAME() intrinsic CALL did not always work and sometimes corrupted memory. Dec 4 2001 (Release 4.4) o The SAVE file revision has been changed from 2.11 to 2.12 in order to support new features in dL4 4.4. Full upward compatibility is provided, so program files created by earlier versions of dL4 can still be used. Programs created by this release of dL4 can be used by earlier releases of dL4 4.x if the programs do not use any of the new features. o Two new GUI mnemonics have been defined: 'WCBQRYBUF' and 'WCEQRYBUF'. Printing 'WCBQRYBUF' to a window enables special buffering for the data returned by the 'WCQUERY' mnemonic. Normally, sending 'WCQUERY' to a GUI element (such as 'WCSTRING') causes the element to return its current value. For example, sending 'n WCQUERY' where 'n' is the element number of a 'WCSTRING' edit box causes the text in the edit box to be returned as input to the window. This can complicate programming because query results are mixed in with event data such as function keys or GUI element status changes. The special buffering enabled by 'WCBQRYBUF' separates the query results from the event data. Event data can be read by normal INPUT statements, but the query buffer can only be read from "record 1" of the window channel. For example, ! Channel 3 is open to window Print #3;'WCBQRYBUF'; Print #3;'5 WCQUERY'; Input #3,1;S$ In order to read from "record 1" of the default window channel, use the special record number -3 (described below) or the DUPCHANNEL intrinsic CALL. Once a 'WCBQRYBUF' mnemonic is printed, the special buffering mode applies to all windows and persists until a 'WCEQRYBUF' or 'IORS' mnemonic is printed. Like other GUI mnemonics, these mnemonics are supported only when using dL4Term (4.3.1.3 or higher) or in dL4 for Windows. o The special channel numbers -3 and -4 can now be used in INPUT, READ, WRITE, SET, and other I/O statements to perform I/O to the current standard input (-3) and output (-4) channels. This extension is particularly useful when using the 'WCBQRYBUF' input mode since it supports reading from record 1 of the current window channel. o The intrinsic CALL DupChannel() now recognizes the special channel numbers of -3 and -4 as the current input and output channels. This allow access to the current Dynamic Window channel. o A new mnemonic, 'PGMHELPFN', has been defined for dL4 when used with dL4Term or in dL4 for Windows. The mnemonic sequence PChr$(n,"text");'PGMHELPFN' will program function key 'n' ('Fn') to send the character string "text" as input when pressed. In addition to "text", the function key will send the action string of the currently selected GUI element, if any. This mnemonic is similar to 'PGMFN', but can be used to implement context dependent function keys such as help or search keys. 'RF' or 'XX' mnemonics can be used to reset all function keys to their original values of 'Fn'. o A new function, MSC(45), has been implemented to return the GUI element number of the user selected GUI element or a WCQUERYed GUI element. The value returned is not the current element number, but rather the number at the time of the most recent input. For example, assume a user had selected edit box 1, typed 'F6', moved to edit box 5, and then typed 'F6' again. If an INPUT statement read only the first function key value, then MSC(45) would return 1, the selected element at the time the function key was pressed. The value of MSC(45) would not change to 5 until the second function key value was read by an INPUT or READ statement. o A new mnemonic, 'WCRESETFONT', has been defined for dL4 GUI programming. The new mnemonic restores the default font for use by newly created GUI elements. Typically, the mnemonic would be used to clear the font set by a previous 'WCSETFONT' mnemonic. o When using dL4Term, it is now possible to run programs on the user's PC. The statement SYSTEM 31,"C:\\Program Files\\Application\\program.exe",S will try to execute "program.exe" on the user's PC. The variable "S" will be set to zero if the program was successfully started and non-zero if the program couldn't be started. The SYSTEM statement suspends execution of the dL4 program and waits until the program exits. In the default dL4Term configuration, the user will be prompted via a message box to permit or deny running the command. See the dL4Term documentation and readme.txt file for information on changing the message box configuration. This feature requires using dL4Term 4.3.1.2 or later. o When using dL4Term, it is now possible to open a printer on the user's PC on a channel. Opening the "Window Terminal Printer" driver opens the dL4 for Windows "Selected Page Printer" on the user's PC and allows the user to select a printer. The driver supports the same mnemonics and open options as the "Selected Page Printer" driver. The OPEN statement will return an error if the user cancels the printer selection. The driver can be opened directly as in the statement: OPEN #1,"filler" As "Window Terminal Printer" or indirectly using a printer script: OPEN #1,"$AUXPRINTER" where "AUXPRINTER" is a script file found somewhere in the user's PATH on the Unix system. The following is an example of such a printer script: # dl4opts=openas=Window Terminal Printer,options=landscape=t The auxiliary printer mnemonics (such as 'BA' or 'EA') shouldn't be used when the "Windows Terminal Printer" driver is open. This feature requires using dL4Term 4.3.1.2 or later. o Two new mnemonics, 'SUSPENDAUX' and 'CONTINUEAUX', have been defined to suspend or continue output to an auxiliary printer after a 'BA', 'BO', or 'AE' mnemonic has started output to such a printer. These mnemonics make it possible to mix output between the printer and the screen. These mnemonics are currently supported only in dL4Term 4.4, but will they be available in the standard terminal definitions (such as Wyse 60) in the future. o The window driver now supports new settings to control mnemonic behavior in dL4 windows. If the line BDIsBP=True is included in a terminal definition file "[Settings]" section, dL4 will change the behavior of the 'BD' and 'ED' mnemonics in a dL4 window to be identical to 'BP' and 'EP'. If the line BPIsFXBP=True is included in "[Settings]", then 'BP' is treated as 'FX BP' in dL4 windows and 'EP' is treated as 'EP FM'. These two settings can be combined so that 'BD' becomes 'FX BP' and 'ED' becomes 'EP FM'. o The window driver now supports new settings to control mnemonic behavior in dL4 windows. If the line FormattedILDL=True is included in a terminal definition file "[Settings]" section, dL4 will perform insert and delete line operations in dL4 windows even if formatting ('FM') is enabled. Normally, the 'IL' and 'DL' mnemonics are ignored in dL4 windows if formatting is enabled. This feature is not supported by the current version of dL4Term, but it may be supported in the future. o Character attributes, such as reverse video, are now supported in dL4 windows on "magic cookie" terminals where changing attributes use a displayed space on the screen. Such terminals include the Wyse 50, the Televideo 925, and emulations of those terminals. In previous versions of dL4, the BR/BB/BU/BD mnemonics had no effect when displayed in a dL4 window if the terminal used "magic cookies". In order to display attributes on magic cookie terminals, a space character must be displayed at or preceding the point where the attribute is turned on. o The window driver now supports simulating "magic cookie" behavior on any terminal. If the line BRIsBRSP=True is included in a terminal definition file "[Settings]" section, dL4 will change the behavior of the 'BR', 'ER', 'BB', 'EB', 'BD', 'ED', 'BU', and 'EU' mnemonics to mimic that of a "magic cookie" terminal. The mnemonics will output a space character and will change the character attributes to the specified value from the following character up to the associated ending mnemonic. One common use of this behavior is to turn highlighting on and off on a string of characters by printing a 'BR' mnemonic or a space character at a single position preceding the string (the string must be followed by a unchanging 'ER' mnemonic character). This feature can be used on the current version of dL4Term if the dl4term.chwin terminal definition file is used. Note that dl4term.chwin does not support GUI programming. o The window driver now supports a new setting to control the terminal type returned by SPC(13) or MSC(32). If the line TermType=50 is included in a terminal definition file "[Settings]" section, dL4 will return 50 as the terminal type. This setting can be used to set the terminal type in the dL4Term terminal definition file. o The "scoansi" terminal definition file has been changed for use with the new SCO OpenServer 5.0.6 (or later) console. The "ansi" terminal definition file can be used with other SCO systems. o A new SYSTEM statement mode has been added to return the number of available 512 byte disk blocks on a file system. The statement SYSTEM 32,"path",B returns in "B" the number of available blocks on the file system that contains the directory or file "path". The SCOPE CONVERT command and LOADSAVE utility "-c" option will convert UniBasic/BITS UNIT mode 3 statements to SYSTEM 32 statements. o Conversion profiles can now define functions to be translated in addition to user CALLs. For example, if the line "ERRMSG$=ERM" is included in a library section of a conversion profile, then loading a program with that profile will convert all instances of the ERM function to ERRMSG$ and the required declarations for the library function will be inserted into the converted program. o Conversion profiles can now include a "[Standard]" section to define the standard pre-defined function names of the source language. This section can be used if there are problems with names that collide with dL4 standard function names (such as "TRIM$"). o Conversion profiles can now include a "[Settings]" section. The "LANGUAGE=xxxx" line in the "[Settings]" section selects the source language for the conversion where "xxxx" can be "IRIS", "BITS", or "IMS". If the source language is "IMS", statements such as 'OPEN #c;"R","Filename"' will be converted to 'ROPEN #c;"Filename"'. o When loading a program using a conversion profile, parenthesized subscripts are now converted to bracket subscripts ("A(5)" becomes "A[5]"). o The syntax of the multiline IF structure has been enhanced to accept an optional "THEN" keyword after an IF or ELSE IF boolean expression. The "THEN" keyword is accepted and discarded. o The LOADSAVE utility now supports a "-C filename" option to perform source-to-source conversions. The command: loadsave -C converted.bas -c convert.prf orig.bas converts the program text source file "orig.bas" to dL4 using the conversion profile "convert.prf" and outputs the converted program text to the text file "converted.bas". The conversion profile can contain an "[OutputFormat]" section with lines such "Indentation=n", "LeftMargin=n", and "TabSpacing=n" to control the formatting of the output lines. The "TabSpacing" value specifies that a tab character should replace each occurrence of "n" leading spaces. These values can also be specified on the loadsave command line by using the "-i n,m" and "-t n" options. o A simple include file feature has been added to the LOADSAVE utility. The INCLUDE statement is recognized only by LOADSAVE and reads source text from a specified file into the program following the INCLUDE statement. The environment variable INCSTRING can be used to specify a space separated list of directories that should be searched when opening an include file. If lines in an include file use line numbers, the lines will be inserted at the specified lines replacing any previously loaded lines with those line numbers. The INCLUDE statement can have both a line number and a label. Example: Include "filename" o A new option, "-n linenumber", has been added to the LOADSAVE utility to specify the starting line number when using source files without line numbers. By using a starting line number other than the default of 1, an open range of line numbers can be left for use by conversion profiles that insert declarations and other header lines. o A program line can now consist of a label without a statement. For example, the line: NEXTFILE: is now legal and will be treated as the label "NEXTFILE" followed by an empty comment ("NEXTFILE: !"). o To improve compatibility with other BASIC languages, it is now legal for a program line to have a FOR statement follow an IF statement. o The CHF#(100 + c) function, which is defined to return the file creation time, has not been supported in previous dL4 for Unix versions because Unix does not record file creation times. In dL4 for Unix 4.4 and later, this function will return the oldest of the access, modification, and inode modification times. Under dL4 for Windows, the function will continue to return the recorded file creation time. o A new channel function, CHF$(1300+c), has been implemented to return the native path of the file open on channel "c". o A new channel function, CHF(1400+c), has been implemented to return the file identification number of the file open on channel "c". In dL4 for Unix, this function returns the inode number of the file. In this release, this function is only supported by the raw file driver. o Channel functions 12 and 13 have been added to the list of channel values displayed by the SCOPE FILE command and in program dumps. o The GET statement can now be used to determine the character set used by data file records. For example, the statement: Get #C,-1299;Name$ stores in "Name$" the name of the character set used on channel "C". An error will occur if this operation is not supported by the driver open on channel "C". o The LUMAP runtime parameter can now control whether portable filenames are treated as case-insensitive (default) or case-sensitive. If the LUMAP parameter value begins with "(mixedcase)", all portable (relative) filenames will be treated as case-sensitive. This option only controls how filenames are translated to and from the native filename format; the result of using case-sensitive filenames on a non-case-sensitive file system is operating system dependent. o A new, optional program file format is now available for Unix systems to allow direct execution of dL4 programs from a shell command line. The new format starts each dL4 program file with the line "#!string" where string is a program path. For example, the command: save <755> (exec=/usr/bin/run) programname would save the current program into the file "programname" as an executable script with an initial line of "#!/usr/bin/run". The program file could then be executed directly at a shell command line by typing "programname". The program file would also be usable in dL4 SCOPE, in CALL/CHAIN/SPAWN statements, or in dL4 for Windows. The "exec" line can include options RUN such '-t ""'. In addition to the "exec=" option, executable Unix scripts can be produced by using the "stdexec" or "netexec" options which are equivalent to "exec=/usr/bin/run" and "exec=/usr/bin/run -t". Program files can be made executable on Windows systems by using a unique filename suffix such as ".dl4" and then associating that suffix with the required command line. o A new program option, "STRING REDIM IS LEGAL", has been implemented to make it legal to re-dimension simple string variables without FREEing the variable. The following program creates a string variable with a dimension of 20 and then expands the string to a dimension of 80: 100 Option String Redim Is Legal 110 Dim S$[20] 120 S$ = "Test program" 130 Dim S$[80] 140 S$ = S$ + " with too many characters for DIM S$[20]" 150 Print S$ Note that the original value of S$ is preserved when it is expanded. o Support has been added for DynamicXport Lite. o Channel command 36 (DCC_SETOPENMODE) can now change the exclusive or shared open mode of an open file. This operation is currently supported in Portable/Universal Indexed, Contiguous, or Formatted files. Example: Channel 36,#10;"E" ! change to exclusive open o New intrinsic CALLs SYSRC() and DBASE() have been added to provide compatibility with other Business BASICs. o The standard terminal definition files have been modified to eliminate display problems when using the up and down arrows with the SCOPE history feature. o Two new intrinsic CALLs, RMVSPACES() and RMVSPACESI(), have been added to duplicate the behavior of CALL $RSPCS() in UniBasic and other BASICs. BASIC syntax: Call RemoveSpaces(SOURCE$, DEST$, MODE) Call RemoveSpacesI(SOURCE$, DEST$, MODE) If "MODE" is not equal to one, then "SOURCE$" is copied to "DEST$" with all leading and trailing spaces removed. If "MODE" is equal to 1, then "SOURCE$" is copied to "DEST$" with all spaces removed except those within quotes, all characters after and including an unquoted "!" are removed, and a trailing linefeed is appended if the string ends in a "!". Call RemoveSpaceI() differs in that "MODE" 1 always appends a linefeed and a "MODE" other than 0 or 1 causes an error. o A new intrinsic CALL, WHOLOCK(), is now available to determine what port or process has locked a specific record of a file. The CALL syntax is: CALL WHOLOCK(Channel, RecordNumber, PortNumber [, ProcessID]) where "Channel" is a channel number open to a file and "RecordNumber" is the record number in that file to be tested. If the record is locked, then "PortNumber" will be set to the port number of the process that has locked the record. If "ProcessID" is specified, it will receive the Unix process id number of the process that locked the record. If the record is not locked, than "PortNumber" and "ProcessID" will be set to -1. "PortNumber" will also be set to -1 if the process that locked the record is not a dL4 process (note that UniBasic processes are not dL4 processes) or if the dL4 process is executing on a remote system. In this release, CALL WHOLOCK() is supported only for formatted, contiguous, and indexed contiguous files. CALL WHOLOCK() is an OS dependent CALL and it should not be used in dL4 for Windows. o A new intrinsic string function, DATEUSING$, has been implemented to format date values. The function syntax is: DateUsing$(DateValue#, FormatString$) where "DateValue#" is a date expression to be formatted and "FormatString$" is a string expression containing a mask string. The following formatting codes are recognized in the mask string: D Numeric day of week (0 - 6, 0 is Sunday) d Numeric day of week (0 - 6, 0 is Sunday) DAY Day name in upper case (SUNDAY, MONDAY, ...) day Day name in mixed case (Sunday, Monday, ...) Day Day name in mixed case (Sunday, Monday, ...) DY Abbreviated day name in upper case (SUN, MON, ...) dy Abbreviated day name in mixed case (Sun, Mon, ...) Dy Abbreviated day name in mixed case (Sun, Mon, ...) DD Numeric day of month zero filled ("01" - "31") Dd Numeric day of month space filled (" 1" - "31") dD Numeric day of month space filled ("01" - "31") dd Numeric day of month ("1" - "31") DDD Numeric day of year zero filled ("001" - "366") Ddd Numeric day of year space filled (" 1" - "366") ddd Numeric day of year ("1" - "366") HH Numeric hour of day zero filled ("00" - "23") Hh Numeric hour of day space filled (" 0" - "23") hH Numeric hour of day space filled (" 0" - "23") hh Numeric hour of day ("0" - "23") MM Numeric month of year zero filled ("01" - "12") Mm Numeric month of year space filled (" 1" - "12") mm Numeric month of year ("1" - "12") MONTH Month name in upper case (JANUARY, FEBRUARY, ...) month Month name in mixed case (January, February, ...) Month Month name in mixed case (January, February, ...) MON Abbreviated month name in upper case (JAN, FEB, ...) mon Abbreviated day name in mixed case (Jan, Feb, ...) Mon Abbreviated day name in mixed case (Jan, Feb, ...) NN Numeric minute of hour zero filled ("00" - "59") Nn Numeric minute of hour space filled (" 0" - "59") nN Numeric minute of hour space filled (" 0" - "59") nn Numeric minute of hour ("0" - "59") PM "AM" for time before noon, "PM" for time afterward pm "am" for time before noon, "pm" for time afterward P "A" for time before noon, "P" for time afterward p "a" for time before noon, "p" for time afterward Q Numeric quarter of year ("1" - "4", 1 is Oct - Dec) q Numeric quarter of year ("1" - "4", 1 is Oct - Dec) SS Numeric second of minute zero filled ("00" - "59") Ss Numeric second of minute space filled (" 0" - "59") sS Numeric second of minute space filled (" 0" - "59") ss Numeric second of minute ("0" - "59") TH Ordinal number in upper case ("1ST", "2ND", ...) th Ordinal number in lower case ("1st", "2nd", ...) WW Numeric week of year zero filled ("01" - "53") Ww Numeric week of year space filled (" 1" - "53") wW Numeric week of year space filled (" 1" - "53") ww Numeric week of year ("1" - "53") YYYY Four digit year YY Two digit year Formatting codes are replaced by their associated values. Any unrecognized characters will be copied unchanged to the result string. Example: Print DateUsing$(Tim#(0), "MM/DD/YYYY HH:MM") o The SPC(n) function has been extended to return the numeric value of the environment variable "SPCn" where "n" is an undefined SPC function number. For example, if the environment variable SPC105 was set to "65", then SPC(105) would return a value of 65. User defined SPC functions should be defined at 100 and above to avoid conflicts with any future standard SPC functions. o The intrinsic CALL ENV() has been extended with a second syntax: Call Env(mode,name$,value$) where "mode" is 1 to read the environment variable "name$" into "value$" and "mode" is 2 to set a new value. For mode equal to 1, the following special value names will be recognized and will override any environment variables with the same name: PID Unix process id GID Unix group id UID Unix user id o The intrinsic CALL PROGRAMDUMP() has been extended with a second syntax: Call ProgramDump(filename$,options$) where "filename$" is the output file path and "options$" can be set to the string value "append" to cause PROGRAMDUMP() to append the new output to the output file rather than replacing the output file. o The FoxPro Full-ISAM driver now supports mixed case filenames when used in an absolute path. The standard file extensions (".dbf", ".cdx", and ".fpt") will always be lower case under Unix. o A new open option, "DataExt=xxxx", has been added to the FoxPro Full-ISAM driver to support opening dBase files that do not have the standard ".dbf" extension. o A new character set, "Stripped ASCII", has been added to support conversion of files from other BASICs where the most significant bit of 8-bit characters is ignored. o The Portable Formatted, Contiguous, and Indexed-Contiguous file drivers now support a new option, "NUMMAP=IEEE-LE", for files that contain least significant byte first ("Little Endian") data. This feature has been added to support conversion of non-dL4 data files. o Bug fixed: a SYSTEM "cmd" statement sometimes caused odd characters to be displayed when using dL4Term. o Bug fixed: the CHF(600) function returned incorrect values for directories. o Bug fixed: the timeout equals -5 option to disable record locking on formatted and contiguous files did not work. May 15 2001 (Release 4.3.2) o The pipe driver ('OPEN #1,"$xxxx"') now accepts multiple "# dl4opts=" lines at the beginning of a shell script. This makes it easier to specify multiple pipe driver options. Each option line can contain multiple options, but an individual option cannot span lines. o Bug fixed: dynamicXport could not be used if it was licensed as a demonstration product. May 1 2001 (Release 4.3.1) o The DynamicXport runtime support in dL4 has been updated to support the current release of DynamicXport. o The DynamicXport intrinsic CALLs (DXOPEN, DXCLOSE, DXGET, DXSET, and DXURL) require a DynamicXport product license in the SSN before the CALLs can be used. Without a valid DynamicXport license, the CALLs will generate an error 38. o Platform 29 (Power AIX) now uses the same binaries as Platform 07 (PowerPC AIX). o A new open option, "binary=", has been implemented in the pipe driver. If a pipe is opened with a "binary=true" option, all data written to or read from the pipe will be passed as 8-bit binary characters without any formatting or end-of-line processing. Example: Open #1,"(binary=true)$program" o A new MSC() function, MSC(44), has been implemented so that programs can determine if the Dynamic Windows system is active. If Dynamic Windows is "on", MSC(44) will return one. If Dynamic Windows is "off", then MSC(44) will return zero. o A new intrinsic CALL, NCRC32(), has been implemented for compatibility with UniBasic 7. The CALL provides the same functionality as the existing CRC32() intrinsic function. The new CALL has the following syntax: CALL NCRC32(C, S$ [, O]) where "C" is a ten digit or larger numeric variable that will receive the calculated CRC-32 checksum, "S$" is a string value to be checksummed, and "O" is an optional numeric value containing a CRC-32 value from a previous calculation. o Phantom ports created by the PORT statement, the SPAWN statement, or by CALL $TRXCO are no longer counted when checking the licensed number of users. o The checksum utility in the tools directory now accepts a "-m" option to generate MD5 checksums instead of CRC-32 checksums. Mar 13 2001 (Release 4.3) o Four new intrinsic CALLs have been added to support writing DynamicXport applications. The new CALLs are DXOPEN, DXCLOSE, DXGET, and DXSET which are described in the DynamicXport programming documentation. DynamicXport is a new middleware product from Dynamic Concepts. This release of dL4 contains a beta release of these CALLs and the CALLs will not function after June 1, 2001. o A new startup option, "-X", has been added to support DynamicXport applications. DynamicXport applications written in dL4 are started with the command "run -X programpath". This format identifies the program as a DynamicXport application and configures dL4 with necessary options. The "-X" option disables all terminal translation. o A new startup option, "-B", has been added to set the initial I/O mode of the standard input and output channels to binary I/O without input echo. o A local and private cache for dL4 programs has been implemented to improve program load performance, particularly when programs are loaded from remote networked file systems. The feature can be enabled by setting the environment variable DL4LOCALCACHE to the size of the desired local cache in bytes. The cache resides in process memory, is not shared with other users, and may increase process size. Programs in the local cache are identified by the absolute path of the program file. If a program file is modified while it is in the local cache, the old version in the local cache will continue to be used until the program is flushed from the cache by lack of use or a local SAVE command to the file. To effectively use the local cache, programs should be in the first program search directory (for example, the first directory in the LIBSTRING environment variable). o A new function, MSC$(8), has been implemented to return the native path separator string. Under dL4 for Unix, MSC$(8) returns "/". o The IOBO mnemonic now accepts either "\377\" or "\177\" as the count terminator. o A LEVEL command has been implemented in SCOPE to return the dL4 revision level and the license number. o A SHOW command has been implemented in BASIC to find all lines containing a specified variable name. The command syntax is identical to that of the FIND command. o A new mnemonic, 'WCDEFAULTBTN', has been implemented to create default push buttons. These buttons are identical to those created by the 'WCBUTTON' mnemonic except that the button is marked as the default and will be triggered by the user typing ENTER if the focus is on the button or on another non-pushbutton GUI input element. The arguments to the 'WCDEFAULTBTN' mnemonic are identical to those of the 'WCBUTTON' mnemonic. Note: if the 'nWCFOCUS' mnemonic is used to set focus to a non-default pushbutton, that button becomes the default. o A new mnemonic, 'n FONTCELL', has been implemented to set the font height by specifying the line height, rather than the character height. The mnemonic argument is in grid coordinates and is identical to that used by 'n FONTSIZE'. o New mnemonics 'n,d GRIDENGLISH', 'n,d GRIDMETRIC', and 'n,d GRIDFONT" have been created to provide a higher precision method of setting the coordinate grid. In these new two parameter mnemonics, "n" and "d" are the numerator and denominator of a fraction which is passed to the mnemonic as a parameter. Thus the mnemonic string '1000,72 GRIDENGLISH' is equivalent to 'x GRIDENGLISH' where "x" is equal to 1000/72. Since 'GRIDENGLISH' sets the coordinate grid in 1000ths of an inch, this sets the grid to 1/72 inches (points). These mnemonics are supported by the Windows page printer driver. o A new mnemonic 'n LANDSCAPE' has been defined to select landscape mode (n equals 1) or portrait mode (n equals 0) on printers. o A new mnemonic 'n LPI' has been implemented to set the number of lines per inch when printing to the Windows Page Printer driver. o A new mnemonic 'n CPI' has been implemented to set the number of characters (columns) per inch when printing to the Windows Page Printer driver. A second form, 'n,d CPI' has been implemented to use the fraction "n/d" when setting the number of columns per inch. o A new mnemonic, 'MARGIN', has been implemented to set horizontal ('w MARGIN') and vertical ('w,h MARGIN') margins in the Windows Page Printer driver. The arguments to the mnemonic are margins expressed in grid coordinate system units. For example, if the current coordinate grid was tenth inches ('100GRIDENGLISH'), then a half inch left margin could be set by '5MARGIN' or a half inch left margin combined with a one inch top/bottom margin could be set by '5,10MARGIN'. o A new mnemonic, 'n WCWHERE' has been added for use with dL4Term. The mnemonic causes the GUI input element that currently has the input focus to return the action 'n' string as input. If the window itself has the input focus, a 'CR' will be returned. o When using dL4Term, a new option value, 32, has been implemented for all GUI input elements. The new option causes any loss of input focus to be reported as an input value change (option 2). o Enhancement: the 'BEGIN' mnemonic can now be sent to GUI edit boxes (such as 'WCSTRING') to place the cursor at the start of the current text and to select the current text for replacement. The user can tab or otherwise move to a different GUI element to leave the value unchanged or type new characters to completely replace the existing value. To send the 'BEGIN' mnemonic to an edit box, the edit box must be the currently selected GUI element (via 'nWCSELECT'). The following example could be used to initialize the contents of a newly created 'WCSTRING' edit box and select the contents for replacement: Print '4WCSELECT';"Initial Data";'BEGIN';'0WCSELECT'; The 'n BEGIN' mnemonic can be used to perform the 'BEGIN' function on GUI element "n" and also set the input focus to that element: Print '4BEGIN'; o The intrinsic CALL ENV() has been extended to support runtime modification of the SPC(5), SPC(7), and MSC(7) values. Setting the values of the SPC5, SPC7, or MSC7 environment variables will control the subsequent values returned by the SPC() and MSC() functions. o A new open option has been added to the pipe driver. The CLOSEWAIT option sets the time in seconds that the driver will wait for the child process to exit when the channel is closed. The option "CLOSEWAIT=0" will not wait at all. The pipe driver does NOT terminate the child process when the CLOSEWAIT period expires; the driver simply closes the channel and leaves the child process running. Example: Open #1,"(closewait=120)$$script.sh" o A new driver, "Bidirectional Command Pipe", has been added to allow opening bidirectional pipes to an operating system command or program. Using the driver, it is possible to start a command and then both write data/commands to the command and read the results. o A new utility, VERINDEX, has been added to the tools directory to verify the index portions of Portable or Universal Indexed Contiguous files. The utility can detect various forms of index corruption. o A new utility, MAKEHUGE, has been added to the tools directory to convert Indexed Contiguous or Formatted files to Huge Indexed Contiguous and Huge Formatted files. This permits the files to grow beyond 2 gigabytes in size. Note: huge files can be used only on Windows NT, Windows 2000, and some Unix systems. o A new intrinsic string function, Trim$(), has been added to remove both leading and trailing blanks or other whitespace. Since Trim$() is an intrinsic function, a "DECLARE INTRINSIC FUNCTION TRIM$" statement is required in order to use the new function. o A new intrinsic CALL, FlushAllChannels, has been added to request the operating system to write all system buffers to disk for each open channel. The CALL performs a "CHANNEL #c,DCC_SYNC,1;" on each open channel. This CALL was added for use on Windows systems and has no effect when called in dL4 for Unix. o A new open option, "RTRIM=", has been implemented in the Full-ISAM drivers. If the option "RTRIM=TRUE" is used, all trailing spaces are removed when reading fields. The option is case insensitive and an argument of "T" is identical to "TRUE". Example: Open #1,"(rtrim=t)test.dbf" o The GET statement can be used to retrieve the local or remote IP addresses associated with a socket. Example: Get #c,-1598;RemoteAddress$ Get #c,-1599;LocalAddress$ By using the DUPCHANNEL intrinsic CALL, these operations can also be used on the standard input and output channels if they are open to a socket. o A printer directory has been added to /usr/lib/dl4 to contain sample printer scripts and printer definition files. In this release, the printer directory contains the file pcl.prf which is a printer definition file for use with pfilter and PCL based printers. o The UniBasic Indexed-Contiguous file driver now supports alternate character sets, ANSI1 and Toggled ANSI1, that preserve the lower 8 bit binary value of data read into or written from strings. These character sets can be used if application store binary information, such as packed numeric fields, in strings. If these alternate character sets are used, mnemonic characters can not be read from or written to UniBasic Indexed-Contiguous files. This option requires recompiling and relinking the UniBasic Indexed-Contiguous file driver (driver/ubcontig.c) using the dL4 Development kit. See the file driver/ubcontig.c for instructions on how to enable the alternate character sets. o Behavior change: directories can now be opened with the ROPEN statement or the "" access permissions. o Behavior change: for compatibility with UniBasic, the function MSC(n) now returns -1 for n equal to 4, 8 through 17, 21 through 29, and 36. Previously, a parameter range error was generated. Note that UniBasic returns a random platform dependent value for MSC(29) rather than -1; this behavior was not intended and has not been duplicated in dL4. o Behavior change: a file specification can now contain more than one file attribute specification. Multiple specifications are concatenated before the attributes are processed. Example: Build #1," [1:40] <00> filename" o Bug fixed: a statement with a trailing backslash such as "10 A=1 \" was not recognized as a syntax error and sometimes caused a memory violation if the program was executed or SAVEd. o Bug fixed: a SCOPE command with inverted line numbers ("500 DELETE 100") sometimes caused a memory violation. o Bug fixed: printing the value of a non-existent structure variable member sometimes caused a memory violation. o Bug fixed: when using dl4Term, closing a window and then immediately opening a new window with the same channel number caused some output for that new window to be directed to the main window. o Bug fixed: the UniBasic Indexed-Contiguous file driver sometimes reported an error when the "" attribute was specified when building a file. o Bug fixed: if a non-existent record was deallocated in a Portable or Universal Indexed-Contiguous file, the driver ignored the operation (as intended for compatibility), but incorrectly decremented the records-in-use count. o Bug fixed: single character reads or reads with timeouts from a text file or pipe sometimes lost characters. o Bug fixed: address violations sometimes occurred when SAVEing a program. o Bug fixed: entering the debugger or enabling a program trace while in a SWAPped program sometimes caused file corruption. o Bug fixed: a parameter mismatch in an EXTERNAL FUNCTION call sometimes caused a memory violation. o Bug fixed: printing a mnemonic with a string parameter to the PFILTER utility sometimes caused following mnemonics to fail with a bad character error. o Bug fixed: '/usr/bin/run -t ""' sometimes failed. Aug 3 2000 (Maintenance release 4.2.1) o An error which could potentially lead to the corruption of the index portions of Indexed-Contiguous files has been corrected. All 4.2 or 4.2 beta installations of dL4 for Unix should be updated to dL4 4.2.1. The error was specific to Unix and did not effect dL4 4.2 for Windows. Aug 1 2000 (Release 4.2) o The maximum size of the index portion of Portable and Universal Indexed-Contiguous files has been increased to 256 gigabytes on Unix systems that support files larger than 2 gigabytes. The size of the data portion is limited only by the amount of storage space available. To use this feature a file must be created as a "Portable Huge Indexed-Contiguous" or "Universal Huge Indexed-Contiguous" file. Example: Build #1,"[1:40]File" As "Portable Huge Indexed-Contiguous" Currently, huge files are supported on UnixWare 7 and AIX 4.3. They are not supported on SCO OpenServer because OpenServer does not allow user files to be larger than 2 gigabytes. In order to build huge files on UnixWare 7 or AIX, the file system must be configured to support files larger than 2 gigabytes. Please see the UnixWare or AIX OS documentation for instructions on how to configure file systems. To share huge files across a network, both the file server and the client systems must support sharing files larger than 2 gigabytes in size. o The "H" option letter ('BUILD #1,"[10:100]file"') can be used to select the "Huge" format when creating a Portable Formatted, Contiguous, or Indexed file. This option allows a file to grow to more than 2 gigabytes in size on operating systems that support user files of that size (see above). o A new driver class, "Email", has been added to send email. In this release, the driver requires sending email through an SMTP server such as provided by Unix servers or most ISPs. Non-SMTP mechanisms may be added in the future and should not require any application changes unless SMTP specific options (such as "SERVER=") are used (use the DL4EMAILSERVER environment variable instead). After opening the driver, a program simply prints text to be emailed to the channel. Files can be attached and sent as part of the email by using 'ADD #c;"Filename"' statements. If a file consists of multiple files, such as the data and index portions of an Indexed Contiguous file, each subfile must be sent with a separate ADD statement. The path argument to the driver is an email address list. An email address list consists of one or more space separated email addresses. Email address lists are also used in the options such as "TO=" described below. The driver options parameter ("(xxx)") can be used to pass the following options: "TO=addresses" one or more destination email addresses. May be used in addition to or instead of placing addresses in the path. "BCC=addresses" one or more "BCC" email addresses. These are similar to "CC" addresses, but they are not included in the email header. "CC=addresses" one or more "CC" email addresses. "FROM=addresses" one or more sender addresses. "REPLYTO=addresses" one or more reply addresses. This option would only be used if the reply address was different from the sender ("FROM=") address. "SUBJECT=text" email title or subject. The text may be placed in quotation marks if necessary. "SERVER=name" SMTP server name. Defaults to the value defined by the DL4EMAILSERVER environment variable or the host system. "PORT=n" SMTP port number. Defaults to the standard SMTP port (25). "PROTOCOL=name" Email protocol name. Only "smtp", the default protocol, is supported by this release. "ATTACHAS=name" File attachment encoding type. This option must be specified if file attachments will be used. The value of "name" must be either "mime" or "default" (which is "mime" in this release). "TIMEOUT=n" timeout period in tenth-seconds for communication with the SMTP server. This option is used to change the default 5 minute timeout period and should not be needed. A program using the email driver must specify at least one destination email address in the path or a "TO=" option. At least one "FROM=" email address must be provided. The SMTP server name is optional and can be defined via the "SERVER=" option or in the DL4EMAILSERVER environment variable. If the server name is undefined, the host Unix system will be used. After all email text has been output and all attachments added, the email channel should be CLOSEd to actually send the email. If the channel is CLEARed, the driver will attempt to cancel the email. Example: Open #1,"(From=name@domain,AttachAs=Mime) nobody@dynamic.com" As "Email" Print #1;"Test the email driver" ! Append the file "Filename" as an attachment Add #1;"Filename" Close #1 Please change the "From=" and destination email addresses to your own email address before using this example. o When using dL4Term, the 'BA', 'EA', 'BO', 'EO', 'AE', and 'AD' mnemonics are now supported to direct output to an "auxiliary printer". When printer output is enabled, output will be sent to the printer selected via the dL4Term "Printer" sub-menu of the "Preferences" menu. When sending output to a Windows printer, a document will be considered complete and all pages will be printed when auxiliary output is disabled by an 'EA', 'EO', 'AD', or 'XX' mnemonic. A program should not expect to be able to suspend output with 'EA', 'EO', or 'AD' and then later continue output on the same printer page. These mnemonics can be used without dL4Term if the mnemonics are defined in the appropriate terminal definition file and if the mnemonics are output to the main window. When using Dynamic Windows ("WINDOW OPEN"), the "WINDOW OFF" statement or the CALL DUPCHANNEL intrinsic should be used to output the mnemonics to the main window. o When using dL4Term, the 'WS', 'ES', 'SO', and 'SF' mnemonics are now supported to display a status line the bottom of a window. The 'WS' mnemonic redirects all output to the status line until an 'ES' mnemonic is output. The 'SO' (status line on) and 'SF' (status line off) mnemonics control whether the status line is visible. Note: the mnemonics and status line text must be output to the window that will contain the status line. When using Dynamic Windows ("WINDOW OPEN"), the "WINDOW OFF" statement or the CALL DUPCHANNEL intrinsic should be used to output status line mnemonics to the main window rather than the current window. These mnemonics can be used without dL4Term if the mnemonics are defined in the appropriate terminal definition file. o When using dL4Term, the 'WD' and 'NR' mnemonics have been implemented to change the current font size to either the default font size or 6 tenths of the default font size. Assuming a default window width of 80 characters, the 'NR' mnemonic will set the font size to provide a width of 133 narrow characters. Both mnemonics clear the window with the equivalent of a 'CS' mnemonic. o A new mnemonic, 'PGMFN' has been defined to control the text sent by the 'Fn' function keys. The mnemonic sequence PChr$(n,"text");'PGMFN' will program function key 'n' ('Fn') to send the character string "text" as input when pressed. This mnemonic is currently defined in the dL4Term terminal definition file only, but it can be implemented for other terminal types by modifying their terminal definition files. The 'RF' or 'XX' mnemonics can be used to reset all function keys to their original values of 'Fn'. Note for dL4Term users: the 'PGMFN' mnemonic supports function keys 'F0' through 'F63', however, dL4Term's default configuration only defines keys for 'F1' through 'F12'. If, for example, you want to use shift-F1 as 'F13' in dL4Term, use the dL4Term "Preferences->Keyboard" menu item to define the additional keyboard translation. The "Keyboard" dialog and methods of copying keyboard configurations are described in the dL4Term Reference Guide. o A new mnemonic, 'INVERT' has been defined to invert colors within a specified region. The mnemonic has the following forms: 'INVERT' - Invert colors from the current position to the end of the current line. 'n INVERT' - Invert colors from the current position for 'n' characters. 'w,h INVERT' - Invert colors from the current position within a rectangle of 'w' characters width and 'h' characters height. 'x1,y1,x2,y2 INVERT' - Invert colors within rectangle defined by the points 'x1,y1' and 'x2,y2' of the current coordinate grid. This mnemonic is currently defined in the dL4Term terminal definition file, but it may be possible to define this operation for other terminals by modifying their terminal definition files. o When using dL4Term, the user can end their telnet session by selecting the DISCONNECT menu action, the exit button, or the "close" action of the system menu. Exiting in this manner prevents the application from cleaning up any partially written transactions. A new mnemonic, 'ONCLOSE', has been defined to allow applications to control such exits. The 'ONCLOSE' mnemonic has the following forms: PChr$(0,"text");'ONCLOSE' - Display "text" within a message box and give the user a choice of exiting dL4Term or continuing the application. PChr$(1,"text");'ONCLOSE' - Display "text" within a message box and prevent the user from exiting dL4Term. PChr$(2,"text");'ONCLOSE' - Prevent the user from exiting dL4Term and treat "text" as input for the program. PChr$(0,"");'ONCLOSE' - Disable any previously set ONCLOSE action. Programs using the 'ONCLOSE' mnemonic should output a null action ('PChr$(0,"");'ONCLOSE') or an 'XX' mnemonic before exiting to clear the ONCLOSE action. o Behavior change: input to any window can now be read from any window. For example, if windows are open on channel 1 and channel 2, pressing a button in the window open on channel 1 will create input that can be read on either channel 1 or channel 2. This change makes it easier for programs to use more than one input window at a time. Note that when using multiple windows, all of the GUI elements should have unique element numbers even if the elements are in different windows. o A new driver, "TCP Listen Socket", has been added. The "Listen" driver allows a dL4 program to be a server for socket requests. For example, dL4 program S running on ServerA might use the "Listen" driver to open a listening socket on port 9631 of ServerA. Programs on other systems could then open sockets to port 9631 of ServerA to exchange data with program S. The "Listen" driver is used by opening a port number using the "Listen" driver: Open #1,":9631" As "TCP Listen Socket" The open will return immediately. To accept the next queued connection to that port, the program opens a socket using channel 1 as the parent socket: Open #2,{1} As "Socket" This open to channel 2 will not return until another program on the local or a remote system opens a socket to port 9631 of the local system. Once the open returns, channel 2 can be used to perform normal socket read and write operations to transfer data from or to the client program. When the transaction is finished, the server program closes channel 2 and performs another open against parent channel 1 to accept the next queued client request. The example program below provides a date and time service on port 9631. While the program is running, any telnet utility can be used to connect to port 9631 and receive the current date and time. The current date and time will be printed to the client once every ten seconds until the client closes the connection. Dim I$[100],3%,I Open #1,":9631" As "TCP Listen Socket" I = 0 Do Open #2,{1} As "Socket" I = I + 1 Do Try Print #2;"Session";I;Tim#(0);"\15\\12\"; Else Exit Do Try Read #2,-1,-1,100;I$ Else Rem If Spc(8) <> 123 Exit Do Loop Close #2 Loop If multiple clients attempt to open port 9631 at the same time, only one request will be accepted at a time. The other clients will be queued by the operating system until the current connection on channel 2 is closed. The client program will receive an error if the total number of queued requests exceeds an operating system defined number (usually a small number). Client programs should be prepared to retry opens if the server is busy. Normally, a null server name (":9631") should be used to open a listening socket on local system. The server name can be specified to open a listening socket on a specific network interface. The "opentime" option can be used to specify a maximum number of seconds to wait when opening a new queued connection: Open #2,{1,"opentime=10"} As "Socket" A record locked error (error 123) will be generated if the open times out. Lists of pre-defined TCP port numbers can be found at many web sites include www.iana.org. When writing a "listening" socket program, the port number should not conflict with a port number used by a needed or common pre-defined service. In general, the port number should be greater than 1023. Note: on most Unix systems, a "listening" server can be implemented more robustly by having the system inetd process listen for requests and start dL4 processes as required. For example, adding the line below to /etc/inetd.conf will cause inetd to listen on the port "test" and start the dL4 program "pgm.dl4" whenever anyone attempts to open a socket on the port "test". test stream tcp nowait user /usr/bin/run run -t "" /home/user/pgm.dl4 The dL4 process will run as the user "user". The socket will be open on the standard input and output channels and accessible through normal INPUT and PRINT statements. The port number "test" must be defined in the file /etc/services. The '-t ""' option to run tells run to use the default terminal definition (see the "-t" option description elsewhere in this document). After modifying the file /etc/inetd.conf, the system must be rebooted or a SIGHUP signal must be sent to the inetd process. o Two new GET statement operations have been defined for use with TCP socket drivers. The following statement will retrieve as a character string (usually "nnn.nnn.nnn.nnn") the remote IP address connected to the socket open on channel C: Get #C,-1598;S$ This function would typically be used with the "TCP Listen Socket" driver to determine the IP address of a client system. The statement below will retrieve the local IP address connected to the socket open on channel C: Get #C,-1599;S$ o A new SYSTEM statement mode has been implemented: SYSTEM 30 executes system commands with standard input and output assigned to /dev/null. This eliminates most screen output by the system command. The new mode syntax is: SYSTEM 30,CommandString$ SYSTEM 30,CommandString$,CommandStatus where "CommandString$" is a string literal, variable or expression and the optional "CommandStatus" is a numeric variable that receives the operating system execution status of the command. o Four new terminal definition file options have been added in the "[Settings]" section for use with dL4Term. These settings change the normal behavior of some mnemonics to match alternate definitions used by some developers. Each setting is a boolean value which, if set to "TRUE", enables the associated mnemonic behavior. The new optional settings are: SwapWDAndNR - Redefine the 'WD' mnemonic to select a narrow font and a typically 132 column window width. Redefine the 'NR' mnemonic to select the normal wide font and the normal window width. BCIsNR - Redefine the 'BC' and 'EC' mnemonics to function just like the 'NR' (Narrow Font) and 'WD' (Wide Font) mnemonics. These redefinitions are not effected by the SwapWDAndNR setting. BXIsNR - Redefine the 'BX' and 'EX' mnemonics to function just like the 'NR' (Narrow Font) and 'WD' (Wide Font) mnemonics. These redefinitions are not effected by the SwapWDAndNR setting. BXIsWD - Redefine the 'BX' mnemonic to function just like the 'WD' ('Wide Font') mnemonic. The 'EX' mnemonic is redefined to function as a 'NR' (Narrow Font) mnemonic. These redefinitions are not effected by the SwapWDAndNR setting. Example: [Settings] SWAPWDAndNR=True BXIsNR=True o A new special output macro can be defined in the "[OutputMacros]" section of a terminal or printer definition file. The "Illegal" macro can be used to define a single character to be output whenever an illegal output character is output. Example: [OutputMacros] Illegal=? o Change from earlier beta release: the email driver now uses native filenames for attachments. o Enhancement: the socket driver now supports a "partial=" option to control whether a read terminates as soon as at least one character has been read (default behavior) or waits until the destination variable has been filled ("partial=true" behavior). This option is specified in the option field when opening a socket. Example: Open #1,"(partial=true)server:servicename" As "Socket" o A "-u" option has been added to the BASIC DUMP command to produce listings with line numbers even for programs that don't need line numbers. o A command history has been added to SCOPE so that the up and down arrow keys can be used to recall previously typed commands. The user can then repeat or edit the command. o The BASIC EDIT command now supports using the up and down arrow keys to select additional lines for editing after entering EDIT mode. o The BASIC LOAD command has been extended to load programs from program files as well as source files. o A "tools" directory has been added to the standard runtime installation. This directory contains the following utilities from the dL4 samples package: buildfi - utility to create Full-ISAM files buildxf - utility to create Indexed-Contiguous files checksum - utility to calculate 32-bit CRC file checksums convert.prf - sample conversion profile pgmcache - program cache utility query - utility to display file type and characteristics term - utility to display port status or terminate programs o A "-t terminaltypepath" option has been added to RUN to select the terminal definition file. This option may be needed when using RUN to execute dL4 programs as network services via inetd. o Behavior change: to increase compatibility with the character oriented window driver, independent windows can now be moved using the main window coordinate grid regardless of which window driver is used. In previous versions of dL4, independent windows could be moved if the character oriented driver was used, but this was an "accidental" feature. Independent windows without the "TITL" style will no longer have a minimal border when using dL4Term. Note: most applications should use child windows (see below) rather than independent windows. o Behavior change: The child window open syntax: OPEN #c,{"title","style",width,height,parent,column,row} As "Window" has been extended so that 'parent', which is normally the channel number of the parent window, can be -1 to indicate the main window. This feature makes it unnecessary to use the CALL DUPCHANNEL intrinsic to assign a channel number to the main window. o Behavior change: the 'WCNUMBER' mnemonic now produces an edit box that accepts signed floating point numbers rather than just non-negative integers. The numbers must be in the format <"."> where the sign and decimal point are optional. Entering an illegal character will be rejected. Note: the edit box may return a return a value such as "-", ".", or "-." if the user starts to enter a legal number but never adds the expected digits. o The 'MH' (Move Home) mnemonic is now supported in edit boxes such as 'WCSTRING' to move the current position to the beginning of the text in the box. o Behavior change: the intrinsic CALLs DateToJulian(), FormatDate(), JulianToDate(), and VerifyDate() now ignore spaces preceding numeric values rather than requiring zero filled values. o Behavior change: the statement "INPUT TIM -1;String$" when used with "OPTION INPUT TIMEOUT SIGNAL OFF" no longer generates an input timeout error, it simply returns any available input characters into "String$". o Two previously optional intrinsic CALLs, GetGlobals() and SetGlobals(), are now standard CALLs and do not have to be installed using the development kit. o Two Windows 95/NT oriented intrinsic CALLs, GetRegistry() and PutRegistry(), have been implemented to return errors whenever called under Unix. This addition permits programs using the CALLs to be successfully linked in dL4 for Unix. Programs should ignore the errors or take alternate action to replace the registry functionality. o Bug fixed: if the debugger was entered when the main window was using a grid coordinate system other than '1GRIDFONT', the "?", "WF", "WS", and "WH" commands did not work correctly. o Bug fixed: using CALL PROGRAMDUMP() after using the debugger sometimes caused a memory violation. o Bug fixed: duplicate structure definitions (DEF STRUCT statements using the same structure name) were not reported as errors. o Bug fixed: FoxPro files created outside of dL4 with duplicate keys in a unique index could not have their index file rebuilt by the DCC_REBUILDINDEX channel command. o Bug fixed: the intrinsic CALL DateToJulian() did not work in modes 2 and 6. In addition, the CALL required a longer string than necessary in 2 digit year modes and permitted too short a string in 4 digit year modes. o Bug fixed: when used with dL4Term, the 'NR' and 'WD' mnemonics did not update the MSC(33) and MSC(40) function values (number of columns). o Bug fixed: when using dL4Term, a selection in a list box or drop-down list box is reported immediately if the value changed option is used. o Bug fixed: when using dL4Term, selecting a value from a drop list of a GUI element was not reported when requested by the WCACTION mnemonic. o Bug fixed: the dL4Term terminal definition file now defines the DELETE key as a delete character input action. o Beta bug fixed: text printed to the email driver after adding an attachment file corrupted the attachment. o Beta bug fixed: normal and huge Indexed-Contiguous files could not be opened at the same time. o Bug fixed: a FoxPro Full-ISAM file with memo fields and a deleted record index did not have the memo fields written when new records were added. o Bug fixed: if a FoxPro Full-ISAM file containing duplicate keys with trailing blanks was re-indexed using a third-party tool, a memory violation could occur when adding another duplicate key with trailing blanks. This problem was most likely to occur when the keys were completely blank. o Bug fixed: the ProgramDump() intrinsic CALL did not report the current position correctly. o Bug fixed: a terminal or printer definition file that didn't define any characters within the "[OutputMacros]" section could cause a memory fault during output. o Bug fixed: the statement 'CHAIN ""' will successfully exit a program even if "OPTION CHAIN FAILURE IS ERROR" is used. o Bug fixed: a memory violation could occur if a SAVE command was executed after an immediate mode statement. o Bug fixed: a program cache belonging to an older version of dL4 will be ignored. Note: when using multiple version of dL4 and a program cache, each version should use a different cache name in the DL4CACHE environment variable. Nov 17 1999 (Release 4.1) o Support has been added for graphical user interface (GUI) programming when dL4 is used with dL4Term, a GUI terminal emulator for Windows 95, Windows 98, and Windows NT. This allows dL4 GUI programs to run under both dL4 for Windows and dL4 for Unix. dL4Term is installed on Windows PCs and uses a standard Telnet connection to communicate with Unix host systems. Rather than emulating a character oriented terminal, dL4Term supports a GUI oriented terminal model with multiple windows and graphic controls such as buttons and list boxes. dL4Term is a separately available licensed product. Visit our web site at www.unibasic.com or contact the Dynamic Concepts Sales department for more information on dL4Term. o When used with dL4Term, the following new mnemonics can be used for graphical user interface programming: 'WCBUTTON' - Create button 'WCCHECK' - Create check box 'WCRADIO' - Create radio button 'WCNUMBER' - Create numeric input box 'WCSTRING' - Create character input box 'WCPRIVATE' - Create character hidden input box 'WCLABEL' - Create a label for an input box 'WCTEXT' - Create multi-line character display box 'WCMEMO' - Create multi-line character input box 'WCLIST' - Create selection list box 'WCEDITLIST' - Create editable selection list box 'WCLISTDROP' - Create drop down selection list 'WCEDITDROP' - Create drop down editable list box 'WCMENU' - Create menu 'WCMENUACTION' - Create menu action item 'WCMENUCHECK' - Create menu check box item 'WCMENURADIO' - Create menu radio button item 'WCMENUSEP' - Create menu separator 'WCENDMENU' - End menu or sub-menu definition 'WCGROUP' - Group graphical elements 'WCSELECT' - Select current graphical element 'WCENABLE' - Enable user input/selection to/of element 'WCDISABLE' - Disable user input/selection to/of element 'WCQUERY' - Request graphical element to send value 'WCDELETE' - Delete a graphical element 'WCACTION' - Change action performed by input element 'WCFOCUS' - Set current focus to selected element 'WCMARK' - Mark or select item 'WCUNMARK' - Unmark or unselect item 'WCSUBMENU' - Create submenu 'WCSETFONT' - Set font for controls Detailed documentation and example programs for these mnemonics can be found in the dL4 4.1 GUI Tutorial. The tutorial can be downloaded from www.unibasic.com. o When used with dL4Term, the new Windows Terminal driver implements an additional window style, "MODAL". A "MODAL" window disables the main window and any previously created modal window so that they can't be selected by the user. The user is thus required to work in the modal window until the window is closed by the application. When the modal window is closed, the previously active modal window is enabled or, if none, the main window is enabled. The "MODAL" style is ignored if applied to a child window (any window created with a parent channel specified or by the WINDOW OPEN statement). Example: OPEN #1,{"Help","TITL,SCRL,WRAP,MODAL",40,10} As "Window" o When used with dL4Term, the new Windows Terminal driver implements an additional window style, "DIALOG". The "DIALOG" style creates a window that defaults to using the standard system dialog colors. A non-child window using the "DIALOG" style will also be modal. Example: OPEN #1,{"New Account","TITL,DIALOG",40,10} As "Window" o The 'FONTCOLOR', 'BACKCOLOR', and 'PENCOLOR' mnemonics have been enhanced to accept two special color codes in addition to RGB color values. Code -1 selects the standard system text color for dialogs. Code -2 selects the standard system background color for dialogs. For example, printing '-1FONTCOLOR' would select the system dialog text color as the current font color. These special color codes can be used to match the dialog color scheme selected by the user. o Two new mnemonics, 'BACTFN' and 'EACTFN', have been implemented to enable or disable activate-on-function-key input. When activate-on- function-key mode is enabled, an INPUT (or any read) from a terminal or window will be terminated by typing any function key or the normal "enter" keys. A function key is any keyboard sequence such as 'F4' or 'PAGE DOWN' that generates a mnemonic character as input data. Function keys such as 'INSERT' or "right arrow" that are used as edit control keys will not terminate input in this mode. The program can determine what character terminated an INPUT statement by using the KEY clause. Example: Print 'BACTFN'; Input Key TermChar$;"Prompt: "Response$ Print 'EACTFN'; If TermChar$ = 'F9' Goto DisplayHelp If TermChar$ = 'MU' Goto EditHistory o New graphic features have been added for use with dL4Term. The following new mnemonics can be used with dL4Term: 'GRIDENGLISH' Set the coordinate grid to thousandths of an inch times the parameter ('nGRIDENGLISH') from the upper left corner. The mnemonic string '100GRIDENGLISH' sets the grid to tenths of an inch and so the cursor position "@35,51" would position to a point 3.5 inches to the right and 5.1 inches down from the upper left corner. 'GRIDMETRIC' Set the coordinate grid to hundredths of a millimeter times the parameter ('nGRIDMETRIC') from the upper left corner. The mnemonic string '1000GRIDMETRIC' sets the grid to centimeters and so the cursor position "@6,10" would position to a point 6 centimeters to the right and 10 centimeters down from the upper left corner. 'GRIDFONT' Set the coordinate grid to the line height and average character width of the current font divided by the parameter ('nGRIDFONT') from the upper left corner. The mnemonic string "10GRIDFONT" sets the grid to tenths of the line height and character width. The cursor position "@105,75" would position to 10.5 columns to the right and 7.5 lines down from the upper left corner. Note that the grid is based on the current font and will not change if the font size is changed unless another 'GRIDFONT" mnemonic is output. When using variable width fonts, the column size is based on the average character width. 'FONTFACE' Set the font to the specified font name. The font name must be specified as a string parameter using the PCHR$() function as in the following statement: PRINT #1;PCHR$("Times");'FONTFACE' 'FONTSIZE' Set the font size to the parameter ('nFONTSIZE') times the grid height unit. 'PENCOLOR' Set the pen color to the parameter ('rPENCOLOR') where the parameter is an RGB color value. 'PENWEIGHT' Set the pen width to the parameter ('nPENWEIGHT') times the grid unit. 'LINETO' Draw a line using the current pen using the current position as one point and the specified coordinates ('x,yLINETO') as the ending point. 'RECTTO' Draw a rectangle using the current pen using the current position as one corner and the specified coordinates ('x,yRECTTO') as the opposite corner. 'RECT' Draw a rectangle using the current pen and the specified coordinates ('x1,y1,x2,y2RECT'). 'ELLIPSE' Draw an ellipse using the current pen to fit the rectangle defined by the specified coordinates ('x1,y1,x2,y2ELLIPSE'). The current grid definition is used for column and row values returned by the MSC() function. Note that a screen inch or millimeter may not match an actual inch or millimeter. Each dL4 window has a separate coordinate grid definition and current font. o Spaces can now be used in filenames and directory paths. Such filenames and paths must be enclosed in quotes. Examples: save "program name with spaces" OPEN #1,"''Filename with Spaces''" Note that quotation marks in dL4 string constants are represented by two consecutive single quotes. Quoted filenames are supported by all statements, all commands, the LIBSTRING runtime parameter, and the LUMAP runtime parameter. o A new intrinsic function ENCFNM$() has been added to dL4 to add quotation marks to a filename if required. The function can be invoked with either one or two string arguments. With two arguments, the first argument will be treated as a directory prefix to be added to the second filename argument. o Portable Formatted or Portable Contiguous files larger than 2 gigabytes in size can now be created on UnixWare 7 or AIX 4.3 systems. Such files are built using the BUILD AS option to specify the "Portable Huge Formatted", "Portable Huge Contiguous", "Universal Huge Formatted", or "Universal Huge Contiguous" drivers. These are new file types using formatted or contiguous file behavior. "Huge" Indexed files will be supported in a future release of dL4. Example: Build #1,"[1:200]Filename" As "Portable Huge Contiguous" In order to build these file types, the file system must be configured to support large files. Please see the UnixWare or AIX OS documentation on instructions on how to configure file systems. To share huge files across a network, both the file server and the client systems must support large files. Note: release 6 of UniBasic does not support "Universal Huge" files. o An OPTION DEFAULT statement has been added to dL4 to set options for all program units in a program module (file). o The SAVE file revision has been changed from 2.8 to 2.11 in order to support new statements in dL4 4.1. Full upward compatibility is provided, so program files created by earlier versions of dL4 can still be used. Programs created by this release of dL4 cannot be used by earlier releases of dL4. o Behavior change: a CANCEL command is now automatically performed if required to perform an edit, RENUMBER, or LABEL command. A warning message is printed to inform the user that the program context has been deleted. Previous versions of dL4 simply displayed an error message and required the user to explicitly CANCEL the program. o Three new drivers have been added to dL4 to create Universal Indexed Contiguous and Universal Formatted files. These drivers are variants of the Portable file drivers with character set, numeric maps, and other options set to match the format of Universal files. New driver names: "Universal Indexed-Contiguous" "Universal Formatted" "Universal Contiguous" o A TCP/IP socket driver has been implemented for the SCO Unix (99), SCO UnixWare (55), and AIX (07 and 29) platforms. A connection can be created using an OPEN statement similar to: OPEN #c,"system:port" As "Socket" where "system" is a network system name or IP address (xx.xx.xx.xx) and "port" is a service name or port number. Character and binary data can be read or written. The following example program reads the current date and time from the host system: 10 Dim L$[100] 20 Open #1,"localhost:daytime" As "Socket" 30 Read #1;L$ 40 Close #1 50 Print L$ The driver does not support "listening" for connection attempts, but standard Unix network service "listening" and startup mechanisms ("/etc/inetd.conf") can be used to configure dL4 programs as network services. o The ERRSET, ERRSTM, ESCSET, ESCSTM, INTSET, and related statements can now be used in external procedures. o The command "RETURN" has been added to the debugger. This command causes execution to continue until the current procedure exits. o The command " GO" can now be used in the debugger to continue execution at a specific line. The line must be part of the current procedure. o String parameters can now be used in terminal and printer definition files. A mnemonic with string parameters is specified in the file using dollar signs ("$") to represent string parameters. For example, a 'S1' mnemonic with one numeric and one string parameter would be specified as '#,$S1'. The following string operators can be used with string parameters: %$c pop index value i from stack and then push the i'th character of the string stack onto the stack. %$l pop index value i from stack and then push the length of the indexed string in the string stack onto the stack. %$"cc" Push string literal onto string stack and push string index onto stack. %$D Delete string from top of string stack. %$F Compare, ignoring case, Tos string to N (Tos - 1) strings at Tos - 3, Tos - 5, ... If matched, return integer from Tos - 2, Tos - 4, ... (pairs of strings and integers). If not matched, return zero. o A new arithmetic option, "BITS DECIMAL", has been added to select BITS numeric types. Note that BITS numeric types are not portable. o A new option, "DIALECT BITS", has been added to select the standard BITS options. The statement "OPTION DIALECT BITS" is equivalent to the following group of option statements: OPTION FILE ACCESS RAW,FILE UNIT IS BYTES,DISPLAY AUTO LF OFF OPTION CHAIN FAILURE IS ERROR,CLOSE FAILURE IS IGNORED OPTION IF BY STATEMENTS,INPUT TIMEOUT SIGNAL OFF,STRINGS RAW OPTION OPEN AUTO CLOSE ON,RETURN BY LINES Note that the arithmetic option, "BITS DECIMAL", is not set. Two additional options, "DIALECT IRIS" and "DIALECT STANDARD", have been added to select the "IRIS SUBSCRIPTS ON" or default options. o A new option, "AUTO DIM OFF", has been added to aid in detecting misspelled variable names. When a program that uses "OPTION AUTO DIM OFF" is SAVEd, error messages will be generated for each variable that is not declared in a DIM statement, COM statement, CHAIN READ statement, or parameter list. A "-u" option has been added to the SCOPE CHECK command and LOADSAVE utility to detect undeclared variables in program that do not use the "AUTO DIM OFF" option. o The OPTION FLUSH AFTER STATEMENT ON option causes all write statements to flush the record buffer even if the statement does not unlock the current record. This option provides compatibility with programs that use ROPEN to read locked records and expect those records to contain updates that are currently in progress. This record flushing option is implemented for Formatted, Indexed Contiguous, and Full-ISAM files. Any driver that does not implement the DCC_SYNC operation will silently ignore this option. This option should only be used when necessary for compatibility with existing programs. o The OPTION RECORD LOCK TIMEOUT N option sets the default timeout period for file and database drivers. The number value N is the number of tenth seconds to wait before reporting a record lock error. The value of N must be between -1 (default, wait forever) and 36000 inclusive. This option should be used in converted programs that used the UniBasic LOCKRETRY feature. The option is supported by the Formatted, Indexed Contiguous, and Full-ISAM file drivers. Example: Option Record Lock Timeout 100 Dim S$[40] Open #1,"File" Read #1,3;S$ ! timeout not specified, will wait up to 10 seconds o The "U" option letter ('BUILD #1,"[10:100]file"') can be used to select the "Universal" format when creating a Portable Formatted, Contiguous, or Indexed file. o The Portable Indexed File and Universal Index File drivers now allow opening files created with an index block size of up to 2048 bytes (ISAMSECT equal to 16). A new environment variable, ISAMSECT, can be used to specify the index block size of newly created files as a multiple of 128 bytes. For example, an ISAMSECT value of 16 would cause new indexed files to use an index block size of 2048 bytes (16 times 128 bytes). The default index block size is unchanged and has a value of 1024 bytes (equivalent to an ISAMSECT value of 8). The new ISAMMAXSECT environment variable can be similarly used to change the maximum openable index block size of 2048 bytes to any multiple of 128. The default index block size should be adequate for all uses, but, if a different value is used, a power of 2 (4, 8, 16, 32, ...) is recommended. o Two new mnemonics 'LITNUL' and 'LITCR' have been defined. These mnemonics, if defined in a terminal or printer definition file, can be used to output 0x0000 and 0x000D characters without translation. o A new mnemonic, 'EUROSIGN', has been defined to represent the Unicode Euro currency character 0x20AC. o A new terminal definition file setting "AcceptPartialKey" has been added to control what happens when a function key leadin character (as defined in the "[FunctionKeys]" section) is not followed by expected characters. If "AcceptPartialKey" is set to "TRUE", the leadin characters will be retained as separate input characters. If "AcceptPartialKey" is set to FALSE (the default), the leadin characters will be discarded. To use this feature, define the value "AcceptPartialKey" in the "[Settings]" section of the terminal definition file: [Settings] AcceptPartialKey=True o A DCC_SYNC command has been implemented in the Portable Formatted driver to flush the record buffer without releasing the current record lock. A DCC_SYNC command can be issued by a user program via the CHANNEL statement ("Channel 20,#c;"). o Behavior change: the KILL statement and the SCOPE KILL command now delete unsupported file types as raw files rather than returning an error. o Behavior change: the background window created by a WINDOW ON or WINDOW OPEN statement is forced behind all other windows including those opened on channels (this is a change only for non-windowed terminals: dL4 for Windows, dL4Term, and "[Settings] StartupInWindow" terminals always followed this rule). o Behavior change: the READRECORD and WRITERECORD statements now obey the FILE ACCESS RAW option. o Fix bug: PCHR$() ignored any parameters preceding a string value. o Fix bug: the LOADSAVE "-l" OSN option ignored illegal OSN indices and, on some platforms, caused memory violations when valid OSN indices were specified. Note that the "-l" option uses an OSN index and not an actual OSN number. o Fix bug: positioning to record 0 ("READ #c,0;F$") immediately after opening a channel to a directory no longer causes an error. o Beta bug fixed: binary input ('IOBI') did not work on non-dL4Term terminals. o Beta bug fixed: output of a character with more parameters than the maximum number of supported parameters sometimes caused a memory fault. o Beta bug fixed: the socket driver now translates numeric IP addresses without first attempting a name lookup. Feb 1 1999 (Release 3.2) o The new ForcePortDump() intrinsic CALL causes a target port to abort execution of the current dL4 program, produce a dump listing file, and then exit from dL4. For debugging purposes, it is also possible to trigger a dump listing without causing the program to exit. The dump output is identical to that of the ProgramDump() intrinsic CALL and lists the current execution location of the target program, the CALL stack, current variable values, the status of open channels, and various other values. The caller of ForcePortDump() must either be the same user as that of the target port or be a privileged user such as root. BASIC syntax: Call ForcePortDump(Mode, PortNumber, Status) where: "Mode" is a numeric variable or expression that controls the type of dump produced. If "Mode" is zero, the target port will be requested to produce a dump and then exit. If "Mode" is equal to one, the port will be requested to produce a dump and then continue (this should only be used for debugging because it will interrupt any I/O in progress). "PortNumber" is a numeric variable or expression containing the port number of the target dL4 program. "Status" is a numeric variable that receives the status of call. The value of "Status" will be set as follows by any call that doesn't generate an error 38: 0 Successful, the selected port exists and a dump command was sent to the port. This status does not guarantee that the port actually aborted or generated a dump file. 1 Error, the specified port does not exist. All parameters are required. Error 38, "Error detected by CALLed subroutine", will be generated if an incorrect number of parameters, parameter type, or parameter value is passed to ForcePortDump. To limit attacks on system security, the dump output is controlled by the DL4PORTDUMP runtime parameter. If DL4PORTDUMP is not defined for the target port, then ForcePortDump() will not generate a dump. On Unix, DL4PORTDUMP is an environment variable that must be set in each users environment (perhaps set by the .profile script). DL4PORTDUMP is the filename to which the dump will be written. DL4PORTDUMP must be an absolute path; for example, DL4PORTDUMP might be defined as "/usr/appdumps/DumpFile.txt". The following macro values can be used in a DL4PORTDUMP path string: %PORT% Port number of target port %DATE% Current date ("YYMMDD") %TIME% Current time ("HHMMSS") %name% Value of environment variable "name" These macro values, if used in the DL4PORTDUMP path, will be replaced by their current values. For example, if DL4PORTDUMP was defined with the value "/usr/appdumps/%PORT%.txt" and a dump was triggered on port 15, then the dump would be written to the file "/usr/appdumps/15.txt". o The ProgramDump() intrinsic CALL has been enhanced to use the DL4PORTDUMP runtime parameter, as described above, if the filename parameter is not specified. o A new command has been added to the BASIC mode of SCOPE. The command "PDUMP filename" outputs a ProgramDump() style listing of the current program status to "filename". o A new mode has been added to the PORT statement. PORT mode 5 returns the current line number and library name executing on a specified port. For example, the statement: PORT P,5,S,L$ will return in L$ the current line number of the program running on port P. If the program is executing a line in a library, then L$ will have the format "library:line#" where "library" is the name of the library. As with PORT mode 3, a status is returned in S indicating success (zero) or failure (one, port not attached). o Two new channel functions, CHF(1200+c) and CHF(1300+c), have been defined to return the current column and row positions. o A new driver, "Serial Terminal", has been added to allow programs to open serial communication devices to a Window class driver. Using this driver, input and output to a serial device will follow the same rules as screen and keyboard I/O. By default, end of line characters will terminate input, input edit characters such as backspace will be processed, and data characters will be echoed. The standard 'IOxx' mnemonics can be used to control input characteristics. Similarly, cursor positioning can be used on output if mnemonics are defined in a terminal definition file. The "Serial Terminal" driver accepts the options listed below when opened: Option Argument Use TERM Filename or path Specify terminal definition file to be used with device SPEED Numeric ("9600") Set device dependent line speed DATA String ("8n1", "7e1") Set device dependent data format XONFLOW Boolean ("T" or "F") Enable XOFF/XON output flow control If not specified, all options except TERM use the current system default value of the device. If the TERM option is not specified, the driver uses a simple default terminal definition in which carriage return is recognized as an input terminator. Example: F$ = "(speed=38400,data=8n1,term=/usr/lib/dl4/term/vt100)/dev/tty1a" Open #1,F$ As "Serial Terminal" o The following intrinsic calls have been added: Call AvPort(PORTNUM {,MINPORT {,MAXPORT}}) Call CheckDigits(STRING$) Call CheckNumber(STRING$) Call ConvertCase(MODE, STRING$ {,START}) Call DateToJulian({MODE,} DATE$ {,CONVERTED_DATE$ {,STATUS}}) Call DecToOct(NUMBER, OUTPUT_NUMBER_OR_STRING_VARIABLE) Call Echo(MODE) Call FindF(PATH$, STATUS) Call FormatDate(DATE$ {,CONVERTED_DATE$ {,STATUS {,MODE}}}) Call JulianToDate({MODE,} JULIAN$ {,CONVERTED_DATE$ {,STATUS}}) Call MiscStr({M,}S${,...}) Call ReadRef(CHAN, MODE) Call Rename(LU, OLDNAME$, NEWNAME$, CHANNEL, STATUS) Call String(MODE,...) Call StringSearch({F,}A${,S},T$,P{,N{,S1{,T1}}}) Call Time(T$) Call VerifyDate(DATE$ {,CONVERTED_DATE$ {,STATUS {,MODE}}}) These calls are UniBasic compatible and replace all of the functions in the oldcalls.bas and depcalls.bas libraries of dl4.samples except for CALL DYNWIND(). The date oriented CALLs, like all other dL4 date functions, use "OPTION DATE FORMAT NATIVE" and the native operating system locale configuration (such as the LANG environment variable) instead of the UniBasic "EUROPEAN" and "DATESEP" environment variables. In all programs that use oldcalls.lib or depcalls.lib, each occurrence of "DECLARE EXTERNAL SUB" must be changed to "DECLARE INTRINSIC SUB" for the new calls. In addition, any "EXTERNAL LIB" statement for oldcalls.lib or depcalls.lib should be removed, or, if CALL DYNWIND() is needed, all of the new intrinsic calls should be deleted in oldcalls.lib. For example, in a program that used the DATETOJULIAN and JULIANTODATE calls, the lines: Declare External Sub DateToJulian,JulianToDate External Lib "OLDCALLS.LIB" would be changed to: Declare Intrinsic Sub DateToJulian,JulianToDate Programs that are not changed will run, but they will continue to use the procedures in oldcalls.lib or depcalls.lib. Conversion profiles such as "convert.prf" should be changed to use the new intrinsic calls. A conversion profile defining all of the new intrinsics can be obtained by downloading version 1.4 of the "dL4 Samples & Utilities Kit" from www.unibasic.com. o By default, the pipe driver processes all PRINT statement TAB functions and "comma" alignment before sending text to the printer script. This pre-formatting simplifies printer scripts, but it can not adjust for different font sizes. For example, the TAB function will generate the same number of spaces even if expanded print ('BX') is being used. A new script option, "FORMAT=false", disables the pre-formatting and passes all mnemonics on to the printer script. The printer script can then implement the TAB function ("@x;" mnemonic) and "comma" alignment ('#ALIGN' mnemonic) as required for the varying font sizes. For example, the printer script and printer definition file shown below implement expanded print mnemonics ('BX' and 'EX') on a PCL compatible printer with TAB(x) alignment based on a fixed 10 characters per inch column width. Printer script: # dL4opts=charset=utf-8,format=false,lock=/tmp/lpt1.lk TERMDIR=/usr/lib/dl4/printers export TERMDIR pfilter -c utf-8 pclprinter >/dev/lp00 Printer definition file: [Macros] ; Variable usage ; X current column ; W character width in 10 CPI characters ; a = Increment column counter by current character width ; e = Clear column counter a=%GX%GW%+%SX e=%{0}%SX ; h = Position to specified column at 10 CPI h=%SX\e&a%GX%{72}%*%dH [OutputMacros] ; Initialize to 10 CPI, 6 LPI Init=%{0}%SX%{1}%SW\e(s10H\e&l6D Default=%@%c%Ma Close=\f 'FF'=^L%Me 'CR'=^M^J%Me ; Set to expanded print as 5 CPI, 3 LPI 'BX'=\e(s5H\e&l3D%{2}%SW ; End expanded print and return to 10 CPI, 6 LPI 'EX'=\e(s10H\e&l6D%{1}%SW ; Position to specified column ("@x;") @#=%p1%Mh ; Align to specified column boundary ("PRINT comma") '#ALIGN'=%p1%GW%*%Sw%Gw%GX%Gw%m%-%GX%+%Mh [OutputUnicodeMapping] ; This mapping is set up for 8-bit output on a printer ; using the ISO 8859-1 (i.e. ANSI Latin 1) character set. Set0= 0x0000-0x00ff=0x00 o The pipe driver has been extended to allow redirection of I/O to a specified driver. "OPENAS=name" or "BUILDAS=name" options can be placed in the script "dl4opts" line to specify that an open of the script should cause an OPEN or BUILD using the driver "name". The options "PATH=string" and "OPTIONS=string" can be used to specify the path or options value to be used by the OPEN or BUILD. For example, the statement 'OPEN #2,"$printer"' opens the script "printer" for output on channel 2. If "printer" begins with the line: # dl4opts=buildas=text,path=/usr/printers/printer.out! then output to channel 2 would be directed to the text file driver and written to the file "/usr/printers/printer.out". o The record number -4 has been defined in the text file driver to position to the end of the file. A program can append to a text file with a statement such as this: PRINT #1,-4;"message" o The SCOPE DUMP command has been extended to support output to the pipe driver. The command "DUMP $name" will list the current program to the pipe device "$name". o A new terminal definition file setting "ProtectedNotDim" has been added to control whether protected characters are displayed with the "DIMmed" attribute. Disabling the "DIMmed" attribute makes it possible to fully control the color of protected characters using the normal color mnemonics such as 'BL' or 'FONTCOLOR'. To use this feature, define the value "ProtectedNotDim" in the "[Settings]" section of the terminal definition file: [Settings] ProtectedNotDim=True A value of "True" will disable use of the "DIMmed" attribute for protected characters. o Three open options have been added to the RAW driver for use with serial devices as shown below: Option Argument Use SPEED Numeric ("9600") Set device dependent line speed DATA String ("8n1", "7e1") Set device dependent data format XONFLOW Boolean ("T" or "F") Enable XOFF/XON output flow control For example, the statement OPEN #1,"[1:1](speed=19200,data=8o1,xonflow=t)/dev/tty1a" As "Raw" would open the /dev/tty1a serial port at 19200 baud with 8 bit characters, odd parity, 1 stop bit, and XON/XOFF output flow control. o MSC(43) has been defined and implemented as returning the current screen row. o SPC(19) now returns a license value as a 32-bit number instead of -1. In the current implementation, the license value is the license number. o A new mode has been added to the ProgramCache() intrinsic CALL. Mode 3, as shown below, returns the error message, if any, that was associated with a failure of the program cache initialization. Call ProgramCache(3, errorcode, initialization_error$) Cache errors are not reported when dL4 performs its initialization: any errors are silently ignored and the cache is not used. o Behavior change: when writing strings with the raw file driver, any 'ALIGN' or 'MOVETO' mnemonics are now expanded before performing the write. This supports the use of TAB and comma field separation in PRINT statements to the raw file driver. o Bug fixed: the LET command in the debugger ignored string subscripts if the first subscript was one. Thus, the command 'LET A$[1,1]="X"' was treated as 'LET A$="X"' replacing the string value rather than just the first character. o Beta bug fixed: the argument order of the intrinsic CALL READREF was reversed. o Beta bug fixed: PORT mode 5 sometimes returned a very large line number if the program on the selected port had exited. o Beta bug fixed: intrinsic CALL STRINGSEARCH would fail to find a match if the match occurred at the very end of the dimensioned size of the source string. Sep 9 1998 (Release 3.1.1.1) o Two new standard intrinsic functions, MD5? and ADDMD5?, have been added to dL4. MD5?() returns the MD5 checksum of the first argument. The argument must be either a binary or a string value. An optional second binary argument can be used to pass an intermediate value from a previous call to ADDMD5?(). This allows a combined checksum of multiple values to be calculated. Checksums are calculated against the DIMed size of strings so that zero characters can be included in the checksum. To avoid this, simply pass strings with subscripts. So that string values will produce the same checksums on all platforms, each UNICODE character of a string is forced into a most-significant-byte first ordering for calculation. BASIC syntax: Dim chksum?[16], intermediate?[128] chksum? = MD5?(var) chksum? = MD5?(var,intermediate?) intermediate? = AddMD5?(var) intermediate? = AddMD5?(var,intermediate?) o The mnemonic 'IOTE' is now supported in dL4 windows. o Bug fixed: if a SYSTEM "command" statement failed due to insufficient system resources, the terminal line was left in an undefined state causing the next input to "hang". o Bug fixed: typing the ESCAPE or INTERRUPT character rapidly on a heavily loaded system could cause the terminal line to be left in an undefined state causing the next input to "hang". o Bug fixed: if record zero was deallocated in a Portable indexed contiguous file, that record was never reused. o Bug fixed: deallocating a non-existent record could disable the count-in-use feature of a Portable indexed contiguous file. o Bug fixed: file lock resources were consumed if a file was open on one channel while it was repeatedly re-opened on another channel. This could eventually cause the system lock resources to be exhausted. o Bug fixed: a sequential read immediately after opening a UniBasic contiguous file returned record 1 instead of record 0. o Bug fixed: ":" was not recognized as a separator during LUMAP translation. As a result, the path "2:file" was not translated to the same value as the path "2/file". o Bug fixed: an address violation could occur if an error occurred while evaluating a single line function (DEF = ). Mar 16 1998 (Release 3.1) o The SAVE file revision has been changed to 2.8 in order to support new features of dL4 3.1. A new program file format also significantly lowers program load overhead. Full upward compatibility is provided, so program files created by earlier versions of dL4 can still be used (programs saved by dL4 2.3.1 and earlier will not, however, be placed in the program cache). Programs created by this release of dL4 cannot be used by earlier releases of dL4. o This release requires an SSN authorized for release 3 of dL4. Without such an SSN, dL4 can only be used in single user demo mode. o An OSN (OEM Security Number) based form of program protection has been added to dL4. This protection mechanism is very similar to the PSAVE method in UniBasic. A program saved with the PSAVE command can be loaded only on systems that have been authorized with a developer supplied OSN. Any attempt to run protected programs on an unauthorized system will cause an error 265, "Not licensed to load or create this program". PSAVE protected programs can be modified and re-SAVED on any authorized system, but they can be listed only on systems which have been authorized with a master OSN. The ProgramDump intrinsic can be used in protected programs and any errors that occur while attempting to list a source line will be ignored (variables names can always be listed) The dl4 PSAVE mechanism differs from UniBasic in two ways: 1. There is no "-o" startup option to add new OSNs. Instead, OSNs are added by creating and/or editing the text file /etc/DCI/osn. 2. There is no "-t" startup option to add a temporary OSN. A temporary OSN is instead added by using the SCOPE "OEM TEMP" command which will prompt for an OSN that will be used only by the current SCOPE session. OSNs are created with the makeosn utility that is supplied as part of Passport version 3.6. A PDN (Product Description Number) is required to use makeosn. Please contact the Dynamic Concepts Sales department for information on how to obtain a PDN. To support this protection method, two new commands have been added to SCOPE: OEM and PSAVE. The OEM command lists the currently authorized OSNs. If the TEMP option is used ("OEM TEMP"), the OEM command will first prompt for a temporary OSN to be used only by the current SCOPE session. The OEM command can be used in the SCOPE command, BASIC, and debug modes. The PSAVE command is used to create OSN protected programs. The PSAVE command is identical to the SAVE command except for an optional OSN number that can precede the SAVE filename. For example, the command "PSAVE 2,menu" would save the current program as "menu" after protecting it to require the second OSN listed by the OEM command. Protected programs can be created only if the specified OSN is a master OSN. The PSAVE command is available in the SCOPE command and BASIC modes. A new option, "-l n", has been added to the SCOPE SAVE command and to the LOADSAVE utility to create OSN protected programs. The value "n" is the number of a master OSN as listed by the SCOPE OSN command. o The new runtime parameter LUMAP adds a mechanism to map relative file paths. The LUMAP value consists of one or more space separated value pairs. Each pair consists of a logical directory name, an equals sign ("=") character, and an absolute path. Whenever a relative filename is used, the LUMAP will be searched for a logical directory name that matches one or more leading directory names of the relative filename. If a match is found, the matched portion of the relative filename will be replaced with the absolute path from LUMAP. For example, given an LUMAP value of "5=/usr/accounting Mail=/disk2/Mail", the following filenames would be translated as shown: 5/filename -> /usr/accounting/filename Mail/filename -> /disk2/Mail/filename x/5/filename -> x/5/filename (unchanged because "x" isn't in LUMAP) Functions such as CHF$(800+c) reverse this mapping to return the logical filename. Using the LUMAP shown above, if "5/abc" was opened on channel 2, the actual file opened would be "/usr/accounting/abc", but CHF$(802) would return "5/abc". If more than one logical directory is mapped to the same actual directory ("5=/usr/acct 6=/usr/acct"), then the reverse mapping will map all occurrences of the actual directory to just one of the logical directories. CHF$(800+c) and similar functions perform reverse mapping on all filenames even if the original filename used an actual rather than a logical directory name. Filename mapping is applied to both data and program filenames. Mapping is applied to program filenames before the LIBSTRING directory list is searched. If a program filename contains a mapped logical directory, the filename will be converted to an absolute path and LIBSTRING will not be used. While the intended use of LUMAP is to support logical unit numbers and logical directory names, it is also possible to map multiple leading directories ("Mail/Fred=/disk2/Mail/Barney") or entire filenames. Such usage is not recommended, but it is legal and supported. o The ROPEN statement has been redefined to open files with locking disabled in addition to the previous read-only access. ROPEN is thus equivalent to 'OPEN "filename"'. This new feature permits an application to read records that are currently locked by other processes. This form of open is supported by the Portable Formatted, Portable Indexed Contiguous, UniBasic Formatted, UniBasic Indexed Contiguous, and FoxPro Full-ISAM drivers. Note: reading records that are currently locked may return partially updated or inconsistent data. o The Portable Formatted and Portable Indexed Contiguous drivers have been modified to support reading through locked records on both Unix and Windows. The required changes to the locking protocol are incompatible with previous versions of dL4. Older versions of dL4 should not be used to access files at the same time as this or later release of dL4. o The Portable Formatted, Portable Contiguous, and Portable Indexed Contiguous drivers now support exclusive opens via the "E" access mode ('OPEN #c,"file"') or the EOPEN statement. An exclusive open will succeed only if the file isn't currently open by another dL4 3.1 user. An error 76 will be returned if another user has the file open in either shared or exclusive mode. Once opened in exclusive mode, a file cannot be opened by other dL4 users. To open a file in exclusive mode, the user must have write access to the file. An attempt to open the same file in exclusive mode on two different channels will succeed, but exclusive access will be lost when either channel is closed (this is a UNIX system limitation). o A single memory image of a program or library can now be shared between different processes and users by using a shared program cache. This feature can greatly reduce the amount of memory needed to support multiple users accessing large dL4 programs. Using the cache is largely transparent to both users and applications. Cached program files are accessed using normal program paths and obey the normal rules for lookup and access permission. Programs can be modified and re-SAVEd while the cache is active without disrupting other users. Any users executing the older version of the program from the cache will continue to execute that older version while new users will invoke the most current version. Using the program cache does not require any programming changes in applications. Programs must, however, be reSAVEd (or LOADSAVEd) to use the new program file format. Programs in the pre-3.1 program file format can be executed, but they will not be placed in the program cache or shared between users. The program cache is enabled and configured using the new environment variable DL4CACHE. The value of DL4CACHE is a file specification of the form: " [size] name" where: "" is a standard dL4 file access option such as "<644>" or "". "" is an optional value. "[size]" specifies the size of the program cache as a number of records and a record length in bytes similar to that used for contiguous files. For example, "[256:1024]" specifies a 256 kb cache. Note that a large cache will only consume virtual memory and does not reserve physical memory. If a "[size]" value is specified, the cache will be created if it does not exist. If "[size]" is not specified and the cache does not exist, then no cache will be used. "name" is the name of the Unix semaphore and shared memory resources used by the program cache. Any decimal ("nnn"), octal ("0nnn"), or hexadecimal ("0xnnnn") format name will directly converted to a Unix resource id value (as displayed by the Unix "ipcs" utility). Any other name will be used as a seed to generate a pseudo-random resource name. The standard cache name of "0xdddc0500" should be used unless this value conflicts with other applications or it is desired to maintain several different caches for different groups of users. "name" is a required value. Example: DL4CACHE="<666> [2048:4096] 0xdddc0500" export DL4CACHE If the value of DL4CACHE is illegal or if the cache cannot be accessed, caching will be disabled. The status of the cache can be determined by using mode 0 of the ProgramCache() intrinsic as shown in the "List entries in cache" example shown in the ProgramCache() description later in this document. In order to use a shared program cache, the operating system must be configured to support both shared memory and semaphores. On many Unix systems, the default maximum size for shared memory will need to be increased. Please see your operating system documentation for instructions on how to configure shared memory and semaphores. A program cache is created by the first user that enters dL4 with a DL4CACHE value that specifies a cache size and specifies a cache name that doesn't exist. Once created, a program cache persists until deleted by the ProgramCache() intrinsic (described later in the document) or the operating system is reloaded. The program cache can also be deleted manually by using the Unix "ipcrm" utility to remove the shared memory and semaphore ids used by the cache. Each user accesses the program cache in either the dynamic or the static mode. The cache mode is dynamic if a user has write access to the program cache and static if the user has read-only access to the program cache. Read and write access is controlled by the access permissions specified in the DL4CACHE environment variable (see above). Note that the mode is specific to the user and different users can be setup to use the cache in different modes. If the user's cache mode is dynamic, all programs and libraries are entered automatically into the cache when they are used. If a new program or library is invoked and the cache is full, programs and libraries that have no current users will be deleted from the cache until sufficient space is available. If sufficient space cannot be freed, the new program or library will be loaded into the user's private memory. A typical DL4CACHE value for dynamic mode use is "<666> [16384:1024] 0xdddc0500". This provides a 16 megabyte cache with write access permitted to everyone. A larger or smaller cache can be used depending on the number and size of frequently used programs. The cache is used in a static mode whenever a user lacks write access to the cache. In static mode, the user never enters programs or libraries into the cache. Programs and libraries are loaded into the user's private memory unless a copy of the program file has been loaded permanently into the program cache by a user in dynamic mode via the ProgramCache() intrinsic (described in a later section of this document). Static mode has two very important advantages: it avoids thrashing and offers higher security. A cache used in static mode cannot be corrupted either accidentally or deliberately by a user. Using a cache in static mode is more secure, but it is also more complex. The cache must be created and initialized in dynamic mode before the static mode users enter dL4. For example, suppose a system has two megabytes of frequently used dL4 libraries. At system startup time, a dL4 process would be run with a DL4CACHE value of "<644> [2500:1024] 0xdddc0500". The process would use the new ProgramCache() intrinsic (see below) to add each of the frequently used dL4 library programs to the cache. Other users would then be started in dL4 with a DL4CACHE value of " 0xdddc0500" which provides read-only (static) access. o A new standard intrinsic CALL, ProgramCache(), has been added to dL4. The intrinsic procedure ProgramCache() is used to read the current shared program cache status and to manipulate the cache. An error will be generated if improper arguments or argument values are passed to ProgramCache(). Any error that occurs while processing the operation will be reported by setting the error code argument to a non-zero dL4 error code. BASIC syntax: Mode 0 - Read next entry in cache. Call ProgramCache(0, errorcode, position, filename, usagecount) Mode 1 - Load program into cache as a permanent entry. Call ProgramCache(1, errorcode, filename) Mode 2 - Delete cache when the current process exits. Call ProgramCache(2, errorcode) Where: errorcode - a numeric variable that will be set to 0 if the operation is successful or to a standard dL4 error code if not. For example, if the cache is not available, the statement Call ProgramCache(0,e,p,f$,c) will set the variable "e" to 42 (file not found). position - a numeric variable that determines which cache entry is read. "position" should be set to zero to read the first entry. Each mode 0 call will update the value of "position" so that the next call will read the next cache entry. The precision of "position" must be such that it can contain any value between 0 and 2^32-1 without any loss of precision (a 3% variable is adequate). The caller should only pass "position" values of zero or those returned by the previous mode 0 call to ProgramCache(). filename - a string variable or expression that will receive a program file path (mode 0) or supply a program file path (mode 1). usagecount - a numeric variable set to the number of users of the program. A usage count of -1 indicates that the program has been added to the cache as a permanent entry. Example: Adding a program to the cache as a permanent entry Declare Intrinsic Sub ProgramCache Dim 1%, ErrorCode Call ProgramCache(1, ErrorCode, "MenuLibrary.lib") Users in static cache mode can only use cached programs and libraries that have been added as permanent entries. These permanent entries must be created by a user in dynamic cache mode using mode 1 of ProgramCache(). Once made, permanent entries cannot be individually deleted because there is no way to determine whether or not a static mode user is currently executing the program or library. See the program cache description above for more information on dynamic and static cache modes. Example: List entries in cache Declare Intrinsic Sub ProgramCache Dim 1%, ErrorCode, 3%, CachePos, File$[200], Usage CachePos = 0 Do Call ProgramCache(0, ErrorCode, CachePos, File$, Usage) If ErrorCode Exit Do If Usage < 0 Print "Permanent "; Else Print Using "######### ";Usage; End If Print File$ Loop If ErrorCode = 73 Print "The program cache is not enabled" Example: Deleting the program cache Declare Intrinsic Sub ProgramCache Dim 1%, ErrorCode Call ProgramCache(2, ErrorCode) This example will delete the program cache when the current user exits dL4. The program cache should be deleted if it is desired to increase the size of the cache or if the cache has become corrupted. The cache can be deleted only by the owner of the cache or by the root user. Since the cache cannot be deleted until the user exits, no error is returned if the caller lacks delete permission. All other users should exit dL4 before the cache is deleted. o CALL-by-filename ('CALL "filename'), CHAIN, and SWAP will reuse any library or program files that are shared with the parent program. For example, if a parent program uses "oldcalls.lib" and CALLs a subprogram that also uses "oldcalls.lib", then a single copy of "oldcalls.lib" will be shared between the parent program and the subprogram. This sharing mechanism is not dependent on the shared program cache and is used even if the shared program cache is not enabled. Library and program files will NOT be shared unless the files have been SAVEd (or LOADSAVEd) in the new program file format. o The SCOPE command line now uses LIBSTRING to find BASIC program files. o The SPAWN statement now uses LIBSTRING to find BASIC program files unless an OPTION statement with "CHAIN ALTERNATE DIRECTORIES OFF" is used. An error 206 ("subprogram file not found") will be returned if the specified program cannot be located. o A new optional section, "[Header]", is supported by the conversion profile files used by the CONVERT command and the LOADSAVE "-c" option. This section can be used as shown below to add standard OPTION statements to programs as they are converted: [Header] Line=OPTION STRING SUBSCRIPTS IRIS Line=OPTION BASE YEAR 1988 Lines from the header section are added using the first unused line number and so they may be inserted after the first converted line. o A new mode has been added to the PORT statement. PORT mode 4 returns the name of the current program of a specified port. For example, the statement: PORT P,4,S,F$ will return in F$ the name of the program running on port P. As with PORT mode 3, a status is returned in S indicating success (zero) or failure (one, port not attached). Only the root account should use PORT mode 4 to examine ports that belong to different user ids. o The MSC$() function has been extended to provide a MSC$(7) value which is the hot-key character, if any, that invoked execution of the current SWAP level. The value of MSC$(7) is an empty string ("") if the current program isn't in a hot-key initiated SWAP level. This new value can be used to perform different functions in a hot-key SWAP program based on which hot-key character was entered. o The 'IOBI' and 'IOEI' binary input mnemonics can now be used in dL4 windows. The meaning of binary input is dependent on the operating system environment and so the use of 'IOBI' should be avoided in portable programs ('IOBC' and activate-on-control-character mode may be a suitable replacement). In all environments, binary input disables special treatment of editing keys such as backspace. In the Unix character terminal environment, binary input disables special character recognition, disables multicharacter key translation, and treats all characters as data. Echo should be disabled when using binary input to avoid echoing illegal characters. o The EXAMINE, BREAK, and NOBREAK debugger commands now recognize the filename of the main program in addition to its path (as displayed by the STATUS command). o Two new commands, "WB" and "WT", have been added to the SCOPE debugger to move the debugger window to the bottom ("WB") or the top ("WT") of the screen. Note that a debugger window is only used if dL4 windows are open. o Three new commands, "WF", "WH", and "WS", have been added to the SCOPE debugger to resize the height of the debugger window. The commands set the debugger window to the full ("WF") height, one half ("WH") height, or a quarter ("WS") height of the full screen, The debugger WINDOW command has been extended to accept a single numeric parameter to set the number of lines in the window (the command "WINDOW 6" or "W6" would select a height of 6 lines). o The SCOPE DISPLAY command and the ProgramDump intrinsic CALL have been modified to print repeated array values in a single line using an array slice notation. For example, if the array V had 10 elements and all of the elements were zero except for V[4]=7 and V[8]=9, then the command "DISPLAY V" would produce the following output: * V[0;3],%13 = 0 V[4],%13 = 7 * V[5;7],%13 = 0 V[8],%13 = 9 V[9],%13 = 0 Note that all lines with repeated data are prefixed with an asterisk. o The size and position of the debugger window is retained between debugging sessions until SCOPE exits. o The EXIT command has been added to the debugger so that the user can exit directly to SCOPE command mode. o The BASIC/Debug command SIZE has been extended to accept a "-l" option which causes the sizes and names of all linked libraries to be displayed. o The SCOPE DRIVERS command now accepts a search string to select which drivers are displayed. Example: "drivers isam". o A new standard intrinsic CALL, DupChannel, has been added to dL4. This call allows dL4 programs to duplicate existing open channels onto closed user channel numbers. These duplicate channels can be used to perform I/O in the same way as the original channels. The primary use of DupChannel is to duplicate the standard input and output channels that are used by INPUT and PRINT when a channel isn't specified. By duplicating the standard input or output channel onto a user channel number, a program can apply channel oriented statements such as SET to a standard channel. Because DupChannel duplicates the base standard input and output channels, it can also be used to avoid window tracking when Dynamic Windows are active. Closing the duplicate or original channel has no effect other than freeing the channel number unless all copies of the original channel are closed. BASIC syntax: Call DupChannel(newchannel, oldchannel) Where: newchannel - a numeric variable or expression specifying the closed user channel (0 - 99) onto which the standard channel will be duplicated. An error will be generated if newchannel specifies a channel that is already open. oldchannel - a numeric variable or expression with a value of an open user channel (0 - 99), standard input channel (-1) or standard output channel (-2) to duplicate. The standard input and output channels are the original base channels and not the window channels used by Dynamic Windows. An error will be generated if oldchannel specifies a channel that is not open. o A new standard intrinsic function, CRC32, has been added to dL4. CRC32() returns a 32-bit CRC checksum code of the first argument which must be either a binary or string variable. An optional second numeric argument can be used to pass the CRC value from a previous call and calculate a combined CRC of several variables. CRCs are calculated against the DIMed size of strings so that zero characters can be included in the CRC. Subscripts can be used to limit the number of characters included in the CRC. So that string values will produce the same CRC values on all platforms, each UNICODE character of a string is forced into a most-significant-byte -first ordering for CRC calculation. An error will be generated if an illegal number of parameters, parameter type, or parameter value is used. BASIC syntax: x = CRC32(var) x = CRC32(var, oldcrc) o A new standard intrinsic function, FindChannel, has been added to dL4. FindChannel() returns the first closed channel number in a specified range. If no range is specified, the first channel between 99 and 0 (note descending order) is returned. An error will be generated if an illegal number of parameters, parameter type, or parameter value is used. BASIC syntax: x = FindChannel() x = FindChannel(startchan,endchan) o The Env and SortInString (CALL 65) intrinsic CALLs are now standard intrinsic CALLs. In previous releases, the sources for these CALLs were included in the development kit, but they were not linked into SCOPE or RUN. The effect of using Env to change the value of dL4 runtime parameters is undefined for the running process: the change may or may not effect the value used by the running process. Applications must not depend on the current treatment of environment variables by dL4 because that behavior may change in future releases. Applications should only change environment variables defined by the application itself. o A new option, "NUMMAP", has been added to the Portable Contiguous and Portable Indexed Contiguous file drivers to support converting from UniBasic to Portable Contiguous files. The "NUMMAP" option has two possible values: "IEEE" (the default) and "IRIS" (to use IRIS BCD number formats). This option can be used as shown below with the "CHARSET" option to create a Portable Contiguous file that uses the IRIS BCD number formats and the IRIS character set: BUILD #c,"(nummap=IRIS,charset=IRIS)[n:l]filename" If a file is built this way, records can be copied directly from a UniBasic contiguous file by reading and then writing the entire record using a binary variable. The UniBasic file must contain only IRIS character and IRIS BCD numeric data. This conversion does NOT support copying packed fields because they contain inherently untranslatable binary data. A file created with the "NUMMAP=IRIS" and "CHARSET=IRIS" options will be compatible with UniBasic 6.1 Universal files. o The FoxPro Full-ISAM driver now supports the memo (.fpt) portion of a FoxPro file when deleting, MODIFYing, or DUPLICATEing FoxPro Full-ISAM files. Note: the driver supports reading and writing to memo fields, but it does not use the memo type when creating a file. Memo fields are supported for compatibility with files created using third party tools. o The FoxPro Full-ISAM driver now tries both the normalized and literal names when mapping fields and indices. This allows the MAP statement to support a wider range of field or index names. o String to date conversion ("D# = S$") now uses operating system locale information to determine the most common year, month, and day ordering if "Option Date Format Native" is set in the current program. The operating system locale features and environment variables (such as "LANG") must be configured to use this feature. o The default value of ISAMFILES has been increased from 40 to 50. o A DCC_SYNC command has been implemented in the Portable Index Contiguous driver to flush the record buffer without releasing the current record lock. A DCC_SYNC command can be issued by a user program via the CHANNEL statement ("Channel 20,#c;"). o The maximum parameter value for the PRINT TAB function and the COMMA SPACING option has been increased from 255 to 65535. o The following new TIM functions have been added to return 4-digit years: TIM(14) Current date in the from MMDDYYYY, MM = 1-12, DD = 1-31 TIM(15) Current date in the form YYYYDDD, DDD = 1 to 366 TIM(16) Current year in the form YYYY These functions correspond to the two digit year functions TIM(4), TIM(5), and TIM(8). o A new channel function, CHF#(), has been added to return the last access or last modification date/time of a file. The last access date/time is returned by CHF#(200+c) where 'c' is a channel number. Similarly, the last modification date/time is returned by CHF#(300+c). Note that opening a file will change the last access date/time unless the "Raw" file driver is used. o Linker speed has been improved for programs that use an extremely large number of libraries (> 50). o Behavior change: The first record number of a Portable Indexed Contiguous file can now be set to zero using a mode 1, index 0 SEARCH statement with a status value of 6. The statement must be executed prior to freezing the index definitions. In previous versions of dL4, an attempt to set a first record number of zero was ignored. o Behavior change: the linker has been modified to allow user defined procedures to overload intrinsic procedures. For example, a user program that defines a function called FindChannel will use that function rather than the new intrinsic FindChannel function. o Behavior change: the MODIFY statement can now move files between file systems if required when changing a file path. o Behavior change: Portable Indexed Contiguous and UniBasic Indexed Contiguous files now flush the data record buffer whenever a key is inserted or deleted. This avoids a situation in which, when a new record was inserted, a separate program reading the file and ignoring record locks would receive a "Record not found" error when accessing the new record. Note that a "Record not found" error can still occur if the new record is not written until after the key is inserted. Writing the new record after inserting the key is an application error which must be corrected in the application program (otherwise there is an unavoidable period between the SEARCH and the WRITE in which the key exists, but the data record does not). o Behavior change: the file type autoselection mechanism for UniBasic files has been improved to make it less likely that text files beginning with the strings "CONT", "DATA", "INDX", "ITEM", "SAVE", or "SYST" will be treated as UniBasic files. o Behavior change: PORT modes 3 and 4 will timeout with an error 155, "No messages waiting", if the target port does not return its status information within 10 seconds. Such timeouts most often occur when a program lacks sufficient privilege to send a query to the target port. Previous versions of dL4 waited forever for a response requiring the user to interrupt the program. Note: PORT modes 1, 2, 3, and 4 should not be used if the target port belongs to a different user id and the current user is not "root". o Input timeout ("INPUT TIM") is now supported on phantom ports. o Input characters following a "hot key" (SWAP input action) character are now always left in the input queue and can be read by the SWAPped to program. o Bug fixed: To increase compatibility with BITS programs, the Portable Contiguous and Portable Indexed Contiguous drivers have been changed to follow BITS alignment rules when OPTION FILE ACCESS RAW is used. Using FILE ACCESS RAW, the current file position will no longer be rounded up to an even byte boundary when reading or writing numeric variables or when executing MAT READ or MAT WRITE statements. The new behavior matches that of the UniBasic Contiguous and Indexed Contiguous drivers. If desired, the Portable Contiguous driver (pcontig.c) in the dL4 development kit can be modified to restore pre-3.1 behavior. o Bug fixed: an address violation or memory corruption could occur if an 'EG' (End Graphics) mnemonic was the first character in an output string when using either the UniBasic or IRIS character set. This would most commonly occur when printing to an output pipe using the default character set. o Bug fixed: SCOPE or RUN would "hang" (enter an infinite loop) when attempting to run or link a program that contained a duplicate procedure definition in a library. o Bug fixed: screen output was garbled if 'BP' was used in a dL4 window on a terminal in which the DIM attribute occupied a screen position ("magic cookie" terminals such as the Wyse 50). o Bug fixed: an "Internal error in driver" error was reported when searching a FoxPro Full-ISAM file that had been opened in read/write mode if the file permissions allowed only read-only access. o Bug fixed: a FoxPro Full-ISAM file could not opened if any of the directory names in the path of the file contained uppercase characters. Note that the filename of a FoxPro Full-ISAM file must be in lowercase. o Bug fixed: a FoxPro Full-ISAM key size of more than 127 characters caused the index to become corrupted. Please note that while keys of up to 240 characters are supported, key sizes should be limited to 150 characters or less for efficient index operation. o Bug fixed: if LUMAP was defined and the current directory was one of the directories in LUMAP, then a CALL, CHAIN, or SWAP to a program in the current directory would fail if the program filename did not specify a directory ('CALL "PGM"' rather than 'CALL "1/PGM"'). In addition, a SCOPE "CD lu/" resulted in an "illegal filename" error. o Bug fixed: the cursor is moved to the end of input line when an enter key is pressed during input editing. o Bug fixed: SPC(23) returned -1 instead of "n" after the statement "LIB n" had been executed. o Bug fixed: the FoxPro Full-ISAM driver did not correctly concatenate field names for members of sub-structures. When a member of a record structure was itself a structure, all members of that sub-structure were treated as having the same, incorrect name. o Bug fixed: trailing exclamation marks were not recognized by the DUPLICATE or MODIFY statements for Portable or UniBasic Indexed Contiguous files. o Bug fixed: the SYSTEM statement generated a runtime syntax error if a status variable was used with an external system command ('SYSTEM "cmd",S'). o Bug fixed: converting a string to a date caused an error 15 if the date was numeric and a two digit year of zero was used. For example, the statement 'D# = "14-10-00"' would fail and report an error. o Bug fixed: expressions containing 24 string concatenation operations could cause memory violations or corrupt the current program. o Bug fixed: reading the command line ("INPUT (0,X)C$") after using the debugger could cause memory violations. o Bug fixed: input was echoed incorrectly in insert mode. o Bug fixed: including a space in BREAK/NOBREAK search string (such as in "BREAK /CALL PGM/") resulted in a format error. o Bug fixed: if a newly built and structured Portable Indexed Contiguous file was CLEARed (rather than CLOSEd), the index portion of the file wasn't deleted. o Bug fixed: a PAUSE or SIGNAL 3 interval of more than 10 million seconds caused an error on SCO Unix. o Bug fixed: pfilter sometimes delayed output until subsequent output or a CLOSE occurred. o Beta version bug fixed: an attempt to load a program or library saved by an older version (2.3.1 or earlier) of dL4 would result instead in loading a different, but previously loaded, program. o Beta version bug fixed: if two identical programs were loaded consecutively, they were treated as having the same path. o Beta version bug fixed: UniBasic indexed contiguous files couldn't be opened if the filename used LUMAP. Notes ===== o Like other Dynamic Concepts products for Unix, dL4 requires a functioning Passport daemon to license the system, and an SSN specific to that license number to authorize use of the software. In the absence of SSN authorization, a single-user demo mode is invoked. dL4 requires at least version 3.1 of the Passport daemon program in order to run; as of this writing the current version of the Passport software is 3.6.1. Version 3.6.1 is fully upward-compatible with previous Passport versions and with all other Dynamic Concepts products. If you attempt to run dL4 with a daemon older than 3.1, you will see messages such as: Waiting for response from security daemon ... and eventually an exit. The Passport software is now distributed by Dynamic Concepts as a separate installable product. For many platforms, you can download the latest version of the Passport from the Dynamic Concepts web site, www.unibasic.com, or ftp site, ftp.dynamic.com. o In order to run, scope and run must locate a "terminal description file". The name of this file is taken directly from the TERM environment variable, and the following directories are searched, in order: Directory given in TERMDIR variable, if present Current working directory Directory given in HOME variable, if present The use of TERMDIR is the most practical for long-term setup. The stock terminal description files shipped with dL4 can be accessed by setting: TERMDIR=/usr/lib/dl4/term export TERMDIR o Converting UniBasic/IRIS/BITS programs with user CALL statements may require setup via a "conversion profile". Contact Dynamic Concepts regarding the "dL4 Samples & Utilities Kit" for more information on converting existing programs to dL4. o In order to use CALL TRXCO() or the PORT statement, the executable file "scope" must be within one of the directories in your PATH. Otherwise, the environment variable SCOPE must be set to the path of the "scope" executable, e.g.: SCOPE=/usr/bin/scope export SCOPE o In order to use the SPAWN statement, the executable file "run" must be within one of the directories in your PATH. Otherwise, the environment variable RUN must be set to the path of the "run" executable, e.g.: RUN=/usr/bin/run export RUN o The record locking protocols used by the Portable Formatted and Portable Indexed Contiguous drivers are incompatible with pre-3.1 versions of dL4. The protocol was changed to support reading through locked records on both Unix and Windows. If a Portable Formatted, Contiguous, or Indexed Contiguous file is accessed simultaneously by this release and a pre-3.1 release, the file data may be corrupted. o The "OPTION FILE ACCESS RAW" statement is used to select BITS compatible file treatment and data alignment rules. In pre-3.1 versions of dL4, the Portable Contiguous, Portable Indexed Contiguous, and Full-ISAM Bridge drivers did not properly follow BITS alignment rules when OPTION FILE ACCESS RAW was used. In dL4 3.1, these errors have been corrected. If your programs use the FILE ACCESS RAW option, your programs and file layouts should be examined for compatibility with these changes. Using FILE ACCESS RAW, the current file position will no longer be rounded up to an even byte boundary when reading or writing numeric variables or when executing MAT READ or MAT WRITE statements. If desired, the driver sources in the dL4 development kit can be modified to restore pre-3.1 behavior. o The BASIC save file version for this release is 2.12. These files are fully upward-compatible with versions 2.1 through 2.11, therefore dL4 will run any saved programs produced by versions 1.15 through 3.2.x. Future minor changes in the save file version (2.13, 2.14, etc.) will be upward- but not backward-compatible. Platforms ========= Operating system information for dL4 For Unix 4.4.1 production: ID Platform "uname -a" ---------------------------------------------------------------- 99 SCO Unix sysname sysname 3.2 2 i386