What's New (and un(der)documented!) In 2.12
Published By | Date | Version | Knowledge Level | Keywords |
---|---|---|---|---|
Sprezzatura Ltd | 01 JUN 1992 | 2.12+ | EXPERT | INDEX_TOGGLE, BUILD.INDEX, EXIT_SYSTEM, ASCII, IMPORT, DRVREADY, KEYBOARD, DEBUGGER, @CM_NAMES, @DICTMODE, BREAK KEY, LINEMARKS, MENU.BUFFER, LOGOFF, BATCH.INDEXING, SI.MFS, @SCROLL.MODE, @SCROLL_MODE, @NULL.EVAL, @NULL_EVAL, @PDISK.ON, @PDISK_ON, PURGE.CACHE, EXECUTE, PERFORM, @VARIABLES |
INDEX_TOGGLE
This new subroutine is the answer to many a developer's prayer. In one subroutine it permits the temporary disabling of indexing for any file (thus speeding up reads and non indexed writes) as well as permitting the rebuilding of indexes!
The subroutine takes three parameters as follows
Call Index_Toggle(File_Name, Position, Action)
where
File_Name | Is the name of the file to be operated on. Note that this is the data file name not the index file name. |
Position | When adding SI.MFS back to the file, dictates where in the chain of MFSs SI.MFS ought to be put. E.G. set to 1 to have SI.MFS as the first MFS in the chain, to 2 to have it second etc. |
Action | Takes three values 0 Disable indexing 1 Enable indexing 2 Enable indexing AND rebuild all indexes for file |
Note that it does not seem to be possible to rebuild all indexes for a file which already has indexing enabled, unless Index_Toggle is called first to disable and secondly to enable and rebuild.
Note further that Index_Toggle is not intelligent - thus if you call it twice with an enable request it will add SI.MFS (and the related information) to the file variable twice. Note further that calling Index_Toggle only affects all subsequent Opens of the file - it will not impact upon file variables already opened.
BUILD.INDEX
It is not strictly true to say that this is a new feature - it was implemented before 2.12 (the use of the period rather than the underscore underlines (sic) this), however the restriction on rebuilds using Index_Toggle makes it seemly to document this at this time. This routine permits the rebuilding of any index within an RBasic program.
Build.Index is a subroutine taking four parameters, these being as follows
Build.Index (FileName, IdxField, IdxRecord, IdxFileVar)
where
File_Name | Is the name of the file to be operated on. |
IdxField | Is the name of the indexed field to rebuild |
IdxRecord | Is a copy of the index description record from the ! file (that record having the same name as the index E.G. Company.Name, Company.Name.Xref etc.). |
IdxFileVar | The file variable of the indexed file - it seems spurious given the fact that the file name is supplied but if not provided the routine will not operate. |
EXIT_SYSTEM
Whilst the R/Basic keyword LOGOFF will log the user off quickly it does not flush out pending index transactions if BATCH.INDEXING is used. The function of this subroutine appears to be simply to ensure that any pending transactions are flushed (and in line with the upgrade documentation, to detach any non-RevTI volumes). Thus call Exit_System in place of LOGOFF. This subroutine takes one parameter - all it seems to do is suppress/display (0/1) the logoff message.
Note that R/Basic LOGOFF and Exit_System do not save the command stack.
DRVREADY
A function that takes one passed parameter (the diskette drive) and returns whether the referenced diskette drive is ready for use, true or false. Note that the diskette drive is referenced by number not letter so
DiskAOk = DrvReady(0) ; * Check Disk A DiskBOk = DrvReady(1) ; * Check Disk B
IMPROVED ASCII IMPORT
One feature that RevTI included without mentioning much is a significantly improved ASCII import routine. The source code for this is provided in the REVSOURCE file and the Import Templates have been substantially amended. Major new features include
The ability to specify multiple DOS files to import into the one AREV file.
Three softkeys in the import window, the first to define import fields, the second to define delimiters including text delimiters for quoted fields and the third "Advanced Options" - dealt with next.
The following Advanced Options are available :-
- Header length - used to indicate existence of header on the DOS file so that it may be skipped on import.
- Create new Revelation file - currently does not work. Choosing "No" crashes when import is attempted if the file does not exist.
- Create new dictionary entries - Choosing "No" causes the system to terminate when it comes across a dictionary item it cannot find in the dictionary of the file being imported to.
- Presize the Revelation file - Choosing "Yes" causes the system to REMAKE the target file using the total record count and the record length. (If the record length is variable it averages the first ten records from the first 1K block). The system further sets the sizelock of the file to ensure that it will not change size whilst the import proceeds. Note that this is only a good idea if the file is empty as otherwise it will be resized smaller than it ought to be.
- Clear the Revelation file - Choosing "Y" causes the system to clear the target file without asking permission first.
- Look for embedded field delimiters - Choosing "Y" causes the system to look for nominated field delimiter characters being embedded in the information being imported.
- Merge with existing data - Choosing "Y" causes the system to only update those fields that are named in the import, otherwise blanks are written to existing data. This permits the importation of periodic information without losing static information.
- Remove and restore indexing - Choosing "Y" causes the system to remove SI.MFS from the file while the import is in progress and the restore it afterwards. Note that as this is a global change other users should not use the file while the import is taking place.
- Suppress restart - If the import process is aborted the system can restart from the place where the last import was stopped. If this is not required then setting this to "Y" will prevent it from happening.
- Batch - Choosing "Y" will stop the import process from hanging part way through the process with an error message (File not available etc.). Used for when the Import is to be run unattended.
- Offsets are actual position - Choosing "Y" causes the system to treat the first start byte as 1, choosing "N" leaves it as 0.
The ASCII import does have a few problems however. If importing more than one fixed length file then EOF marks MUST be explicitly allowed for (using the Shift-F2 popup) if they exist. If they are not the second and subsequent file imports will get out of sync. The Start Byte help suggests that the first byte in the record is 1 whereas it depends upon "Offsets are actual position".
KEYBOARD
The Keyboard function (returns literal text for pressed key) has been internationalised and the results can be amended by editing SYS.TEXT_PARMS KEYBOARD*PARMS.
DEBUGGER
A new command had been added to the debugger, Vx where x is the variable name. This permits the editing of the variable in an edit window, delimited by field marks. Thus a record could be edited simply. Note that unassigned variables can also be assigned at this point but if the program has already fallen over due to the VNAV the program will not be restartable with a G.
If you wish to examine the contents of @SCROLL.MODE from the debugger you must type \@SCROLL_MODE. \@PDISK.ON and \@NULL.EVAL produce "not in symbol table" messages but \@PDISK_ON and \@NULL_EVAL produce "Unknown" messages. This suggests that at some stage of development a global search and replace was executed swapping "." for "_".
NEW @VARIABLES
There are two new @Variables in this release, @CM_NAMES and @DICTMODE. @CM_NAMES is a field mark delimited list of language set names currently loaded. Note that if an attempt is made to load a non-existent language set, the system will display an error message and then load CM_ISO rather than ASCII. @DICTMODE does not seem to be used yet. Note that @LAST.SELECT.PROCESS no longer exists as it has been removed to make way for @DICTMODE.
BREAK KEY AND LINEMARKS
Further to Mike Pope's article later in this issue, the Break Key is now no longer buffered in AREV, so BREAK OFF will ignore all Breaks and not pass them on to the next routine when the break key is reenabled.
MENU.BUFFER
Be warned that as of 2.12 Menu.Buffer (Volume 3 Issue 3) now expects three parameters. The third parameter can normally be safely set to ANY numeric value, it then returns the menu record as normal. Be warned that if a variable is passed for the menu name, and no file is specified (using the @FILE@ nomenclature), Menu.Buffer will return the file it found the menu in (MENUS or SYS.MENUS) followed by a value mark and the menu name.
The third parameter is used to support a new feature which permits the author of replacement menu drivers to conveniently buffer information in the frames array. As Mike Pope's (who I must also thank for help with Menu.Buffer) recent article pointed out, menu records are buffered in the frames array for more rapid access. This increases access speed substantially. However menus frequently have custom information associated with the menu itself, such as screen images and co-ordinates. If the complete menu record with additional information appended is passed in the third parameter, this will be buffered in the frames array and returned next time the menu record is requested. To achieve this, the first parameter must be loaded with the Menu Filename : @VM : Menu Name. Menu.Buffer will then return true or false for whether it managed to locate the information in the frames array. E.G.
Declare Function Menu.Buffer MenuInfo = "MAIN_MENU" ; Menu2 = "" Menu3 = 0 MenuRec = Menu.Buffer(MenuInfo, Menu2, Menu3) * Add in extra information at end of MenuRec MenuRec := @RM : MyInfo /* Now add to frames array using fact that First call would have modified MenuInfo to Contain File : @Vm : Name automatically */ Loaded = Menu.Buffer(MenuInfo, "", MenuRec)
Note that a PURGE.CACHE will wipe out any buffered information from the frames array. These can occur when EXECUTEing or PERFORMing as well as at other times, so ensure that before using the buffered information you check that it is actually there! E.G.
If Field(MenuRec, @RM, 2) Then...
(Volume 4, Issue 2, Pages 6-9)