A file corruption scare at a site with a large ISAMPLUS database led us to delay the official 4.8 release while we reviewed our ISAMPLUS implementation and made a number of minor improvements. The corruption was ultimately traced to a power failure rather than any A-Shell bug, but the improvements discussed here might have helped identify them more quickly, and going forward should permit anyone with concerns about file integrity to achieve a higher level of confidence.
1. ISAMPLUS GET (including GET'NEXT and GET'PREV) and FIND (including FIND'NEXT and FIND'PREV) operations are now verified to make sure that the key in the index matches the key in the data. If not, Basic Error 231 (ISAM+ file needs to be rebuilt) will be generated.
Note that the ERRMSG.xxx message files previously had an incorrect message for error 231. Tthese files have been updated.
2. ISAMPLUS now enforces the rule on the UPDATE'RECORD operation that the record must be locked first. Previously, this was not enforced, which might have let to a situation where a program updated the wrong record if it failed to note that the preceding GET had failed (since GET does not update the record number unless it succeeds.) In the case of DELETE'RECORD, A-Shell had always enforced the must-be-locked rule, but would only allow a record to be deleted if it was the last record locked. While it is virtually always the case that programs lock the record in question immediately prior to updating or deleting it, technically this is not required. A program, could, for example, lock a series of records and then update or delete them. A-Shell now supports this as well. See next item on MAXLOCKS.
3. A new MIAME.INI parameter, MAXLOCKS=## has been implemented to allow you to define the size of the ISAMPLUS lock list that is used to enforce the must-be-locked rules. The default value of 100 (per job) should be more than adequate for virtually all cases so there is probably no need to add this statement to your MIAME.INI. Setting MAXLOCKS=0 will effectively disable the enforcement of the must-be-locked rule.
4. A-Shell now supports a function to verify an ISAMPLUS file without rebuilding it. This is about three times faster than rebuilding and unlike rebuilding, permits you to see if the file was before rebuilding. The easiest way to get at this capability is through the updated ISMUTL.LIT; see below.
5. The ISAMPLUS verify and rebuild operations now cooperate better with Windows, and in addition check for ^C to allow them to be aborted. (If you don't want to allow a ^C abort, you should SET NOCTRLC prior to running ISMUTL.) Previously, under A-Shell/Windows, the application would appear unresponsive to mouse actions, window updating, etc. during these potentially lengthy operations. The internal ISAMPLUS version has been updated to 6.11f, which shows in ISMUTL.
6. ISMUTL.LIT 1.2(125) contains several new features added since the last released version, 1.2(120). First, a new VERIFY option has been added, which is similar to the REBUILD option except only checks the structure of the file. Next, the ability to run various ISMUTL operation in non-interactive mode has been implemented via command line switches:
?Usage: .ISMUTL <filename> {switches}
Switches:
/R - Rebuild file and index(es) unconditionally
/S - Display file stats in non-interactive mode
/V - Verify file
/VRO - Verify in read only mode (skips some tests)
/L - (with /R, /S or /V) Write output to ISMUTL.LST
/A - (with /R, /S or /V) Append output to ISMUTL.LST (create if necessary)
/W - Wait for exclusive access (else abort if not avail.)
These switches make it easier to invoke ISMUTL operations from with command files. In addition to the new VERIFY (/V) option, a read-only variation, /VRO, permits you to run a check on the file even while it is in use. In this mode, the tests that involve comparing the index count to the data count and the data and free list count to the header information are skipped, since file additions and deletions while the test is running would interfere with the counts. But it is still able to verify that the index and file chains are intact, that the keys are in order, and that index keys match the data keys.
7. A new sample utility program, ISMCHK.BP, has been provided in the [7,376] directory, which simplifies the use of ISMUTL to check several files and report the results appropriately. It uses a configuration file (ISMCHK.CFG) to allow you to specify options such as whether to attempt a rebuild if an error occurs during a verify, and whether and where to print, fax, or email the results. (Emailing requires the EMAILX package.) ISMCHK takes a wildcard specification from which it locates all of the ISAMPLUS IDX/DAT file pairs:
.RUN ISMCHK <wildspec>
For example:
.RUN ISMCHK * ; (all ISAMPLUS files in current directory)
.RUN ISMCHK ALL:[] ; (all ISAMPLUS files on entire system)
ISMCHK calls ISMUTL (using the new /V, /VRO, /R, and /A switches) to check and rebuild the files, and then creates a summary of the results, which it inserts at the start of the accumulated ISMUTL.LST file created by ISMUTL. Previous copies of ISMUTL.LST are archived to ISMUTL.001, ISMUTL.002, ISMUTL.003, ISMUTL.004 to allow you to refer back to previous runs. The summary and detailed log looks something like this:
ISMCHK - A-Shell/ISAMPLUS File Integrity Verification Report
Site: MicroSabio In House
Date: Monday, September 8, 2003 04:48:43 PM
Summary:
# Data Files Checked: 2
# Index Files Checked: 6
# Records Total: 32900
# Errors: 1
# Files Rebuilt: 1
# Rebuild Errors: 0
Elapsed Time: 00:00:05
Detailed Log Follows...
! ISMUTL DSK0:ISPTST[150,276] /VRO /A
! 08-Sep-03 16:48:40 MicroSabio In House
!-------------------------------------------------------------------
Verifying ISAM PLUS File DSK0:ISPTST.IDX/DAT[150,276]...
Checking data file ... [ OK ]
Checking index # 1 ... [ OK ]
Checking index # 2 ... [ OK ]
Checking index # 3 ... [ OK ]
! 08-Sep-03 16:48:41 Operation complete
!-------------------------------------------------------------------
! ISMUTL DSK0:ISPTSY[150,276] /VRO /A
! 08-Sep-03 16:48:41 MicroSabio In House
!-------------------------------------------------------------------
Verifying ISAM PLUS File DSK0:ISPTSY.IDX/DAT[150,276]...
Checking data file ... [ OK ]
Checking index # 1 ... [ Error #128: idx/data mismatch ]
Checking index # 2 ... [ OK ]
Checking index # 3 ... [ OK ]
! 08-Sep-03 16:48:41 Operation complete
!-------------------------------------------------------------------
! ISMUTL DSK0:ISPTSY[150,276] /R /A
! 08-Sep-03 16:48:41 MicroSabio In House
!-------------------------------------------------------------------
Rebuilding ISAM PLUS File DSK0:ISPTSY.IDX/DAT[150,276] ...
Checking data file ..... [ OK ]
Rebuilding free list ... [ OK ]
Rebuilding index # 1 ... [ OK ]
Rebuilding index # 2 ... [ OK ]
Rebuilding index # 3 ... [ OK ]
! 08-Sep-03 16:48:43 Operation complete
!-------------------------------------------------------------------
See the ISMCHK.BP source code for further notes on setting up the ISMCHK.CFG file.
7. (UNIX) OPTIONS=CRLF (or OPTIONS=CRNL) now affects auxiliary port output as well. This fix was implemented for A-Shell/Windows in build 832.
8. CGIUTL.SBR option 3 (merge a template page with variables to create a new page) now supports AMOS file specifications. Previously it only accepted native specs, which meant that they were case sensitive, causing confusion over why a file wouldn't be found. It also will now create a log file, CGIUTL.LOG containing the output page, when TRACE=XCALL (or SET TRACE XCALL ON) is active. This is helpful for debugging, since if the output page were invalid, the web browser wouldn't show anything useful.
9. PCKLST.SBR now supports a new flag, 512, which disables the screen save/restore operation (i.e. leaves the pick list box on the screen on exit). Exactly how this would be useful is not clear to me at the moment.
10. (Windows) TCPCLI.SBR and TCPSRV.SBR were, in some cases, returning incorrect error codes. This probably made little difference to most programs, which only cared if an error occurred and didn't care whether it was –1813 or –11243. But it was an annoyance to anyone seeking to actually figure out what the error code meant. Note that if TRACE=SYSERR was set, the proper error code and message was being displayed, but somehow the act of displaying the error message was causing the Windows Winsock library to lose track of what the last error was.
11. (Windows) MIAMEX function 86 now uses the Windows-specific routine to retrieve the error message associated with the specified system error, rather than the standard C routine. This works better for high-numbered errors that only make sense in Windows and thus are not defined in the standard C error message function. Also, we now strip the trailing CRLF from the end of any such messages.
12. Fix an INMEMO display bug in which a box whose right border was against the right edge of the screen would lead to one or two stray border characters in column one after scrolling up and down.
13. Another new sample program, TCPTST.BAS, has been included in the samples directory. This one provides a test/demo of the TCPCLI.SBR and TCPSRV.SBR socket routines.
