====== 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)