Updated October 2020; see History
ISMUTL <fspec>
ISMUTL allows you to create a new ISAM-A file set or perform various maintenance operations on an existing one. ISAM-A file sets consist of a data file with a DAT extension, and an index file containing from one to sixteen logical indexes with an IDX extension. Since the extensions are fixed, the <fspec> should not include an extension, and typically is just a name (e.g. ISMUTL MYFILE).
If the specified file does not exist, you will be prompted for information needed to create the file, including:
Number of records to allocate:
Size of data record:
Type of key (0=*, 1=integer, 2=concatenated, 3=binary):
Does key allow duplicates?
Is key allowed to change?
Size of key:
Position of key:
Extra index block percentage:
Loading factor:
Data file device:
The questions relating to keys will be repeated up to sixteen times if necessary to define up to sixteen indexes. These prompts are designed to be CMD file compatible with the AMOS version of ISMUTL, so that any command files you have to build ISAM-A files will work under A-Shell as they do under AMOS. However, the interpretation or significance of some of the parameters differs, as described below.
The number of records to allocate is completely ignored under A-Shell, because ISAM-A files under A-Shell are automatically self-expanding. The DAT file always starts at zero bytes, and grows with each record added.
The size of the data record is the same as for AMOS, except that the current maximum record size under A-Shell is 8196 bytes.
The "key allowed to change" option is presented for CMD file compatibility, but under A-Shell, the key can always change. (It is considered the responsibility of the application to determine this.)
The extra index block percentage and loading factor options are meaningless under A-Shell, since the index, like the data file, is self-expanding and self-adjusting. (That is not to say that it cannot benefit from reorganization from time to time, but only due to deletions, not to additions alone.)
The data file device, is also ignored, as there is no conceivable excuse for putting the DAT file on one device and the IDX on another. (This was an option under AMOS where devices were often no more than 32 MB, but in the Windows and UNIX world, this is hardly a consideration.)
When the specified file set already exists, ISMUTL instead displays a menu of maintenance options:
LOAD - load a file
CHANGE - change data device name
ADD2ND - add secondary key directory
DELETE - delete existing secondary key directory
INIT - preserves the structure of the file but removes all the data and keys. See History.
REBUILD- rebuild primary & secondary key indexes
DUMP - dump ISAM file
STAT - display statistical information
ADDIDX - add index block
DESCRP - change key description
EXIT - exit to A-Shell
Again, these options are designed to be CMD file compatible with the AMOS version, so that any existing CMD files which execute ISMUTL commands will function the same way under A-Shell.
ISAM-A under A-Shell is implemented via a clone of the Informix C-ISAM access method, which has many advantages over a homegrown implementation, but does suffer from a few small discrepancies with the AMOS implementation. Some of these were mentioned above. Another is that the data file extension is DAT (rather than IDA as for AMOS). This might create a conflict in programs that explicitly looked for that IDA file (although the MAPIDA option in miame.ini may handle most of those). There is also a one-block LCK file which is used for locking but which does not exist under AMOS. Another difference is that the actual record size on disk will be one byte larger than specified, due to the addition of a control byte. This, and the fact that the file grows on a record-by-record basis (unlike the AMOS version which is preallocated in blocks) makes even the data files (as well as the IDX files) not binary compatible between AMOS and A-Shell. To move them between platforms, you have to either use ISMUTL to dump on the source platform and then ISMUTL again to reload from the dump file on the target platform, or you can create a program in BASIC which reconstructs the file from the existing IDA or DAT file (directly, albeit with some programming difficulty).
History
2020 October, A-Shell 6.5.1690: ISMUTL.LIT 1.4(143) enhancement: add INIT function to menu. INIT preserves the structure of the file but removes all the data and keys. The original DAT and IDX files are rolled over to D0? and I0?, up to three generations, i.e. D01, D02, D03.
2017 February, A-Shell 6.3.1545: ISMUTL.LIT 1.4(141) adds an option, when dumping directly from the DAT file, to dump just the active records (default), or just the deleted records, or all the records. The latter two options might be useful in exotic data recovery or other operations. For example, if you accidentally deleted some records, you could dump just the deleted records and then reload them, effectively un-deleting them. Or if you have a large file containing many deleted records, you could split it into two files—one for the active records and one to archive the deleted records—by dumping the active and deleted records separately and then using them to build two new files from scratch.
2017 February, A-Shell 6.3.1545: ISMUTL.LIT 1.4(140) adds a new feature to allow dumping directly from the DAT file rather than from one of the indices.
2010 August, A-Shell 5.1.1191: ISMUTL.LIT 1.3(134) allows 0 as the record size, needed for "pure" indexes. Previously, such an index could only be created via ALLOCATE'INDEXED.
2007 December, A-Shell 4.9.998: ISMUTL.LIT 1.4(132) increases the maximum record size from 8K to 16K.
2005 December, A-Shell 4.9.948: ISMUTL.LIT 1.4(131) eliminates the 2GB limit on the dump/load file, and also adds improved life signs (for long dumps/loads).
2005 December, A-Shell 4.9.947: ISMUTL.LIT 1.4 (130) supports options for Compressed Records and Compressed Indexes.