Installing RFU, RFX and RFT

[Note] Note

This has long been deprecated, but the tools still exist.

The Xtal distribution tape contains some software which is intended to support the updating and maintenance of the system. The program sources rfu.r, rfx.r and rft.r are supplied for these purposes. Their installation is not essential to the use of Xtal but RFU should be installed if at all possible.

RFU is an update editor for applying program updates. It does this automatically by opening the appropriate source files; searching the line identification codes for the correct match; applying the update and closing the file. Xtal updates will be supplied in the correct format for use with RFU.

RFX is the routine used to extract updates from a program source file. It is used to generate an update file that may be read by RFU. This is needed if corrections or enhancements are made to Xtal source files and these must be transmitted to the Xtal Coordinator.

RFT is the routine used to 'tidy' Xtal source files, and to check logical ratmac errors. It is an essential developers tool but not needed by an Xtal user.

Installing the update editor RFU

RFU is supplied as ratmac source code rfu.r. It must be preprocessed, compiled and linked before it can be applied. The most machine-dependent aspect of RFU is the reading and writing of files. Four I/O devices are used: ufile: input file containing the update information (named UPDATE); ifile: the input source file automatically opened by RFU (detailed below); ofile: the output source file automatically opened by RFU; and lfile: the list file or device. These devices are opened with the macros openu:, openi:, openo: and openl:,respectively. Check that the supplied definitions are appropriate for your machine. Note particularly the device numbers, filenames and status codes needed in the open statements. Use the filename UPDATE for the file ufile:unless there is a particular reason for not doing so. The terminal device name for lfile: will depend on the local operating system. Check the definitions of the macros read:, and write: which are responsible for the reading and writing from/to these devices.

An essential requirement for opening the RFU input and output source files, is the appropiate definition of the filename macros dev:, exti: and exto:. The filename for the input file is constructed by RFU as the concatenation of the character strings defined by the 'device' macro dev:,the program code (pcode) from the input PROGRAM line, and the 'name extension' macro exti:. That is the filename dev://pcode//exti:. The output source filename is constructed as dev://pcode//exto:. The total length of each filename may not exceed 12 characters. The definition of dev:, exti: and exto:will be very shop specific. They must enable RFU to find and open the current version of each Xtal program, and to create a new updated copy. For example if the program ABSORB is being updated, pcode will be set as ab and typical filenames would be dsc2:ab.r and

There is one additional safety feature of RFU. The most dangerous aspect of automatic updating occurs when a previous update run has been omitted. Despite the check on matching 'boundary lines', the inconsistency of prior updates can give rise to undetected and insidious errors. RFU provides an additional control line CHECKX which contains the date of the previous update run. This line must precede an update sequence which modifies the definition of the update: macro in the XMACRO file. Here is a typical set of lines at the start of each update run.

** UPDATE Nov93

** CHECKX Sep93

** PROGRAM xmacro

** ............................................................

macro:(version:,3.2)# XM 60

macro:(update:,Nov93/compiler:)# Nov93001

## XM 62

** ............................................................

Since RFU expects to open files with a ratmac filename extension (e.g. xx.r), then there must exist an input file named xmacro.r. The file named xmacro.newwill be output.

Updated source files normally have an extension .new. The user is responsible for renaming these to match the usual ratmac file extension (e.g. .r). Each updated source file will contain an additional lines following the first systemheader: line containing the version dates of updates. These provide an imbedded audit record of the updates applied to a file.

Installing the update extracter routine RFX

RFX searches a source file for lines tagged with '^^' and generates and update file which is suitable for input to the update editor RFU. Note that choice of the two-letter tags is made by the definition of scode: in RFX. As you will see you can use this code repeatedly for successive batches of updates - because they get removed with each application of RFU.

Attach the source as RFXPRG to a run of RFX and the update file will be output as RFXUPD. It should be stressed that the most common difficulty that arises with updating is the deletion of lines. These will get lost from the updating process unless the line before or the line after the deleted line(s) is tagged with ^^ (it does not matter that the tagged line is unchanged). The success of any updating process is completely dependent on the tags being applied consistently. It you miss one it can cause much anguish!

Installing the source tidy routine RFT

RFT is used to tidy ratmac source files for clarity and to make the preprocessing task of the preprocessor more efficient. RFT does the following.

* Separates active code from comments. Active code is left-justified and comments start in column 40 and are converted to lower-case. Full line comments are not altered. Active code in a line following a continue digraph $# is not left-justified.

* Converts alphabetic characters of active code to upper-case except for macro names which are output in lower-case. Characters inside an apostrophe string, or when flagon:(R) is in force, are not changed. Characters in a comment preceeded by double-sharp ## are not realigned and their case is not changed. This feature may be used to make special header lines.

* Converts all 'dot' relational operators (i.e. .GT., etc.) to their symbolic form (i.e. >, etc.). If this conversion is not desirable in Boolean expressions (such asI=J.AND.MASK), the user may prevent it by substituting each period . using the digraph ($.). The above Boolean expression would then be entered as I=J$.AND$.MASK.

* Identifies each brace with a distinctive comment and brace-level and brace-count numbers. For example, the seventh open brace $( , which is nested inside two other open braces, will be commented with 2>>>>>>>>>>>> 7 and the balancing close brace will be commented with 2<<<<<<<<<<<< 7. These serve to highlight statement blocks in the source code.

* Appends a program name and line number to each source line. This is optional according to the definition of the RFT macro linid:. The program name is extracted from each systemheader: encountered in the ratmac source. Line numbers start from this macro.

* Tests for balanced open and close braces, left and right parentheses and square brackets. Error messages are generated if an imbalance is detected.

Here are the implementation procedure for RFT.

Use an editor to examine the macro definitions. The macro linid: enables or disables the insertion of line ID numbers (in columns 73-80). Normally this is set to no:. The input, output, and list files are opened according to the openi:, openo:, and openl: macro definitions. The supplied definitions are for the input file named RFTOLD, the output file named RFTNEW, and the list file named RFTLST. The device numbers are assigned to these files using the macros inp:, out:, andlst:. The macros read:, write: and list: are used to define the input-output for your machine.

Preprocess, compile and link RFT. Prepare a command procedure to execute RFT. A suitable first test is the RFT source code itself, though this has the disadvantage of already being tidy! It should, however, be error-free and enable you to match input with output. Be careful with the renaming of input and output files. The RFTNEW file is your new tidied source, but keep RFTOLD as a backup just in case!