digital equipment corporation · maynard, massachusetts

                   FFFFFFF  UU    UU  TTTTTTTT  II  LL     
                   FF       UU    UU     TT     II  LL     
                   FFFF     UU    UU     TT     II  LL     
                   FF       UU    UU     TT     II  LL     
                   FF       UU    UU     TT     II  LL     
                   FF        UUUUUU      TT     II  LLLLLLL

                          OS/8 File UTILity program

                               Jim Crapuchettes

                          MENLO COMPUTER ASSOCIATES
                         (formerly FRELAN ASSOCIATES)
                                 P.O. Box 298
                           Menlo Park, Calif. 94025

                              Futil Version 6.16

                             Writeup Version 6.5

March 1977 Page i FUTIL - OS/8 File UTILity program NEW FEATURES This version of FUTIL represents a significant revision and expansion over the previous version. The following is a capsule summary of the changes and new features of this version: 1. Chaining support and CCL command addition for convenient setup and startup. Restartable even after CCL command setup. 2. Addition of F4 support in the form of FPP instruction decoding and .LD module mapping and header decoding (including overlay specification). 3. Future MACREL/LINK support in the form of overlay specification support for .SV files and extension of CCB decoding for overlay information. 4. DIRECTORY output format to help in decoding crashed directories and COS format for examination of COS-300 data files. 5. SCAN command to do rapid check for read errors on the current device. 6. Defaults of .SV, .LD and null for FILE command. 7. Modification to "limit" options for WORD and STRING commands for more convenient usage. 8. FILLER variable, used by MODIFY command to fill in specified words whose new contents are not given. 9. Additional output of VERSION, by itself and with ERRORS. 10. Several changes to command names and syntax for more logical usage. 11. Swapping of error messages or write-locked operation (without error messages), as needed. 12. Absolute block number display in MQ register (if available). 13. Order of magnitude improvement in performance for WORD and STRING search commands; WORD is now as fast as SCAN! These new features are paid for by a reduction of the IOT table expansion area from 64 to 32 IOTS and by error message swapping with the USR.
March 1977 Page ii FUTIL - OS/8 File UTILity program Acknowledgements First, thanks need to go to Tom McIntyre of West Virginia University for the use of RUNOFF for the generation of this manual. The significantly increased readability of the manual is directly due to the formatting, paginating and case conversion capabilities of RUNOFF. I want to especially thank several people who read this writeup and commented on it and the program. Tim Clarke, one of my associates, reviewed this writeup many times during its growth. Jim Warren, currently editor of DR. DOBBS JOURNAL, and John Tubbs, currently at the Palo Alto VA Hospital, each made many helpful comments on the writeup. Dennis McGhie, currently at Stanford Research Institute in Menlo Park, made several suggestions on possible additions to the program, the error messages in particular. All of these people were associated with Stanford University or Stanford Medical Center during the time that I worked at Stanford. Also not to be forgotten are many other users who made comments and suggestions during the time that this program has been developing. I also want to mention the groups whose computers were used in the development of this program. The original program, XTAPE, was developed on the PDP-8 belonging to the Tropospheric Propagation Group of Stanford Electronics Labs. Most of the work on FUTIL Version 5 was done on the PDP-8/E belonging to the Department of Anesthesia at the Stanford Medical Center. The rest of the work on FUTIL Version 5 and work on Version 6 was done on the PDP-12 belonging to the Department of Cardiovascular Surgery at the Stanford Medical Center, on the PDP-8/E belonging to the Department of Chemistry at Stanford University and at whatever other computer I could find.
March 1977 Page iii FUTIL - OS/8 File UTILity program TABLE OF CONTENTS: Introduction Why bother with FUTIL? . . . . . . . . . . . . 1 Running FUTIL (including CCL) . . . . . . . . 3 Special characters used in this writeup . . . 5 Special characters used in FUTIL . . . . . . . 5 Access method . . . . . . . . . . . . . . . . 7 Referencing words on the device . . . . . . . 9 Numeric items (or numbers) . . . . . . . . . . 10 Errors (and error messages). . . . . . . . . . 11 Single character (ODT-like) commands . . . . . . . . . 12 "Symbolic" output formats . . . . . . . . . . 14 Word-type commands . . . . . . . . . . . . . . . . . . 16 Output formats . . . . . . . . . . . . . . . . 17 DUMP . . . . . . . . . . . . . . . . . . . . . 18 LIST . . . . . . . . . . . . . . . . . . . . . 19 MODIFY . . . . . . . . . . . . . . . . . . . . 20 Search limits . . . . . . . . . . . . . . . . 23 WORD (search) . . . . . . . . . . . . . . . . 23 STRING (search) . . . . . . . . . . . . . . . 24 SMASK . . . . . . . . . . . . . . . . . . . . 25 SET . . . . . . . . . . . . . . . . . . . . . 27 SHOW . . . . . . . . . . . . . . . . . . . . . 28 FILE . . . . . . . . . . . . . . . . . . . . . 31 WRITE . . . . . . . . . . . . . . . . . . . . 32 SCAN . . . . . . . . . . . . . . . . . . . . . 32 REWIND . . . . . . . . . . . . . . . . . . . . 33 EXIT . . . . . . . . . . . . . . . . . . . . . 33 EVAL . . . . . . . . . . . . . . . . . . . . . 34 Additional examples . . . . . . . . . . . . . . . . . 36 Miscellaneous information Assembling, loading & CREFing the program . . 43 Program execution and memory allocation . . . 43 List device output . . . . . . . . . . . . . . 45 Implementation notes . . . . . . . . . . . . . 45 Command summary . . . . . . . . . . . . . . . . . . . 48 Single-character command output format summary . . . . 49
March 1977 Page 1 FUTIL - OS/8 File UTILity program INTRODUCTION: Why bother with FUTIL? ---------------------- The most obvious answer is that you want or need to use it! This immediately leads to the question: What does it do? FUTIL enables a user to examine and modify from the console terminal the contents of mass storage devices for which an OS/8 handler is available. It is the only program currently available which can be used to patch programs which contain overlays (MACREL/LINK or F4/LOAD outputs). Other possible uses include: application of patches to system programs as reported in Digital Software News; examination and repair of clobbered OS/8 directories; bad block checking and fixup on a device; decimal/octal conversion of double precision numbers; output of the CCB of ".SV" files and the HEADER of ".LD" files; examination of non-OS/8 devices; creation of special directories. Its closest relatives in the form of DEC-supported software are ODT and EPIC. ODT is not used for patching files on devices, however, so the relationship is in form and philospohy. EPIC can patch files on devices and can also compare files (see OCOMP by Dennis McGhie for those comparisons and device independent output that you really wish EPIC would do) and output special paper-tapes of files (if you can't get by with a simple SV2BIN program, at least one of which has been floating around for some time, you'll have to use EPIC). However, though FUTIL does not do comparisons or punching, it does a much more convenient job of patching files on devices, including over thirty (30) commands with many options, four (4) accessing modes for the device, four (4) data input formats, two (2) searches, eighteen (18) status and information outputs and twelve (12) output formats, all of which allow for easy examination of words or blocks on a device in the most understandable way. Supporting these functions is signed double-precision arithmetic expression evaluation which can be used by itself (ever try to convert -135748 to octal?) or in any place in the command syntax that a numeric value is needed. Two simple examples at this point may entice you to read further. Assume that you would like to know what CCL remembers of your last ".UA" command. The remembrances are stored on block 65 (octal) of the system device. As described in the source of CCL, each of the remembrances is allocated 40 (octal, 32 decimal) words in this block, the first four of which contain binary information and the last 34 of which contain the last input command, stored as packed ascii characters. The lines contain the inputs for the commands as follows: TECO and MAKE (line 0), EDIT and CREATE (line 1), COMPILE and EXECUTE and PAL (line 2), UA (line 3), UB (line 4), UC (line 5), and, possibly, FUTIL. So the saved ".UA" command can be listed by outputting the contents of the 4th through 37th words of area 3 in block 65 as packed ascii characters as follows-- .R FUTIL<cr> --call FUTIL from OS/8 EVAL 3*40+4<cr> --calculate start displacement = 00000144 ( 0000100) -- of the 3rd "line" (=144[8])
March 1977 Page 2 FUTIL - OS/8 File UTILity program INTRODUCTION: now list the words of this line with the LIST command, specifying the output format to be PACKED ascii characters and the words to list to be block 65 locations 144 (from above) through 144+33 (the expression for the location of the last word of this "line"). FUTIL responds with the start location and a line characters, and the next location with a multiple of 10[8] as an address and a line of characters. LIST PACKED 65.144-(144+33)<cr> --list the words wanted 0065.00144: DIR R:FUT???.*/E/R=3 0065.00160: --that's it! NOTE on <cr> For the examples above and below, the symbol "<cr>" is used to show that you need to terminate your command lines with a "carriage return". All other lines above are output by the program. Now lets assume that you would like to make the simple patch for OS/8 FORTRAN IV users with an FPP-8/A to use the lockout feature of the FPP-8/A, as given in the August 1976 Digital Software News. This requires changing the contents of location 15776 of FRTS (the Fortran Run Time System) from 400 to 410 (which adds the lockout bit). After doing this you also want to update the date word of the directory entry for FRTS (the 4th word beyond the start of the entry) to show that the file has been updated. You would do the following-- .R FUTIL<cr> --call it SET MODE SAVE<cr> --set FUTIL to a mapped mode FILE FRTS<cr> --look up the file to map FRTS.SV 0671-0722 0032 (0026) 1.327 12/31/75 --"1.327" is start of entry! Now use "ODT" command "/" to open and change 1 word. 15776/ 0400 410<CR> --add LOCKOUT bit SET MODE NORMAL<cr> --switch to unmapped now use "ODT" command "/" with an expression to open the date word, command "@" to output it in "date" format and then put today's date (as an expression) in its place!
March 1977 Page 3 FUTIL - OS/8 File UTILity program INTRODUCTION: 1.(327+4)/ 6375 @12/31/75 (D)<CR> --change file date WRITE<cr> --send out this change NOTE on device access First the file FRTS.SV is changed, and then the OS/8 directory is updated to the current date. Changing the address desired from FRTS to the directory automatically writes out the modified block of FRTS before reading in the directory segment that contains the file name. However, the changed directory segment must be written out explicitly because there are no other blocks to examine for this example. The command set of FUTIL is divided into two groups of commands, as seen above. The first group uses single letters to direct the program in the examination and modification of single words on the device. These commands are very similar to the commands used by OS/8 ODT in both form and function. Examples would be "/", "+" and ";". The second group of commands uses command words to direct the program in the dumping, listing, modifying and searching of the device more or less on a by-block basis. Also included in this group is a set of commands to direct the program in some auxiliary functions including setting and resetting switches and variables within the program, showing their settings and values, etc. Examples of these would be 'DUMP', 'SET' and 'EVALUATE'. Running FUTIL (including CCL): ------------------------------ FUTIL can be called into execution by either the OS/8 Monitor commands "R FUTIL" (as seen above) or "RU dev:FUTIL" or by the CCL command "FUTIL ...", which may optionally include the specification of a device name and/or a file name (with optional extension) and/or several switches. The CCL command is an addition which requires that the standard version of CCL be modified. When execution begins due to an "R" or "RU ..." command, FUTIL performs some initialization (described in more detail in the section on program execution), types a carriage-return and line-feed and is at your command. When execution begins due to the CCL command, FUTIL performs the same initialization, loads any device handler requested, acts on any switches given, performs a 'FILE' command if a file name is specified (with output as described for this command) and is at your command. When started without further direction, FUTIL is set up to access the system device, the 'ERROR' message output mode is set to 'LONG', the access 'MODE' is set to 'NORMAL' and no file is known. To
March 1977 Page 4 FUTIL - OS/8 File UTILity program INTRODUCTION: access some other device, either use the CCL command and specify the name of the device desired (including a ":") or give the command 'SET DEVICE dev' (without a ":"). To set the 'ERROR' mode to 'SHORT', either add "/E" to the CCL command, or give the command 'SET ERROR SHORT'. To use some other access mode, either add a mode switch to the CCL command ("/L", "/O" or "/S") or give a 'SET MODE <mode>' command with a <mode> of 'LOAD', 'OFFSET' or 'SAVE' (note switch to mode correspondence). When in 'OFFSET' mode, the 'OFFSET' to be used can be specified by either adding "=oooo" to the "/O" added to the CCL command, or the command 'SET OFFSET oooo' can be given. Lastly, a file lookup can be done either by adding a file name to the CCL command or by giving a 'FILE' command (with three default extensions). The following is a summary of the options of the CCL command for FUTIL: .Futil [dev:][file[.ex]] [/E][<mode switch>] where only the first character of the command must be given but any other, if specified, must be correct (the standard for CCL commands) and where the <mode switch> can be one of the following: /L set: access mode to LOAD, default .ex to .LD only /O=oooo set: access mode to OFFSET, offset to "oooo" /S set: access mode to SAVE, default .ex to .SV only Finally, when using the CCL command, CCL remembers the command line, requiring the desired options to be entered only once per day until it is desired to change them. To call FUTIL with no options and without using a previously entered command, add an unused switch (such as "/X") to the command. NOTE on second example above The use of this extension to CCL would have somewhat simplified the second example given previously because the command string "FUT FRTS/S" would have called FUTIL, 'SET' the 'MODE' to 'SAVE' and executed the 'FILE' command, all in one swoop! Information on addition of this command is provided in the source of the patch file FUTCCL.PA which is provided with the other FUTIL release files.
March 1977 Page 5 FUTIL - OS/8 File UTILity program INTRODUCTION: Special characters used in this writeup: ---------------------------------------- To help reduce the confusion brought about when this writeup is output in upper case only, the characters single quote ('), double quote ("), angle brackets (< and >) and square brackets ([ and ]) have been used to help separate special items from the words around them. The single quote character is used to surround a word-type command, e.g. the 'FORMAT' option 'SET's up the format in which output is to be done. The double quote is used to surround an item whose actual name is being used, e.g. the "RETURN" key is the key on the Teletype that has that word printed on it. The angle brackets are used to surround the name of a type of item (a syntactical type), e.g. "<n>" means that a NUMERIC ITEM is to be used. The square brackets are used to surround optional items, e.g. "w[ord]" would indicate that the characters "ord" may be supplied optionally. Special characters used in FUTIL: --------------------------------- Several characters, when keyed, cause immediate action from the program. Typing either "CTRL"-"P" (which prints "^P") or "CTRL"-"C" (which prints "^C") will immediately cause the program to stop whatever it is doing. "CTRL"-"P" then causes the program to go back to command input mode and wait for you, while "CTRL"-"C" calls the OS/8 Monitor (as it does with most system programs). During console terminal input, three other keys can be used to help with editing the input string of characters. These keys are "RUBOUT", "CTRL"-"U" (which prints "^U") and "CTRL"-"R" (which prints "^R"). The action of "RUBOUT" and "CTRL"-"U" is exactly the same as it is for the OS/8 Monitor and Command Decoder. The action of "CTRL"-"R" is the same as that of the "LINE-FEED" key for the Monitor and Command Decoder (a different key was required due to the fact that "LINE-FEED" is used for other things in this program so the key picked is the same one used by TOPS-10 for this function). For those users with upper-lower case terminals, the program translates all lower case characters received from the keyboard to upper case. The characters are echoed and handled internally as upper case characters. While this makes use easier, it obviously does not allow any lower-case characters to be input directly. In those cases where lower-case codes are needed in the modification of a file, either use the codes directly or use a text editor. Note that this translation occurs only on input! Lower case characters in a file will be printed to the best ability of the output device. All of the commands are taken in context, i.e. many of the characters which are used in the single character command set will not be considered to be commands if they are included in a line which
March 1977 Page 6 FUTIL - OS/8 File UTILity program INTRODUCTION: begins with a command word or if they are embedded within expressions. The carriage-return ("RETURN") always starts command execution, and is the terminator for all word-type command lines.
March 1977 Page 7 FUTIL - OS/8 File UTILity program INTRODUCTION: Access method: -------------- The program accesses the OS/8 device one OS/8 block (256 words) at a time. For every location specified, the real block and word are determined and compared with the current block in memory. If the desired block and current block are not the same, the <something-changed> flag is checked to see if anything has been changed in the current block. If nothing has been changed, the new block is read in. If something has been changed, the current (modified) block is first written out and then the new block is read in. This action happens correctly even when the access mode is changing because it is done at the level of the OS/8 block number right before calling the current 'DEVICE' handler. The contents of the OS/8 device are therefore not changed unless the block in which changes are made is written out either implicitly, as described above, or explicitly, using the 'WRITE' command (which is discussed near the end of the section on word-type commands). The result is that typing "CTRL"-"C" before writing out the current block (assuming it has been modified) will return to the Monitor without actually modifying the contents of the device itself. Note, also, that only one implicit write attempt is ever made by the program. Should an error occur when the write is attempted (e.g. write locked device), an explicit 'WRITE' command must be given to actually write out the block. If the words within some block are changed accidentally, the <something-changed> flag can be reset by using the 'SET' command to reset the 'DEVICE' (described further along in this writeup) to the same device currently being used. This will reset the <something-changed> flag, the current block in memory, and the file start block and core-control-block/header-block (if they had been set by a 'FILE' command). The resetting of the current block in memory will cause the next access to the device to read in the block desired. The resetting of the file information will require a new 'FILE' command to be given to set it back up. If you can't remember what is the current setting of the 'DEVICE', use 'SHOW DEVICE' first and then 'SET' it the same. Files stored on an OS/8 mass-storage device generally fall into one of four categories. The program has four corresponding modes for accessing the device. The current 'MODE' of the program can be set by the 'SET' command or by chaining (as described previously) and examined by the 'SHOW' command (to be described later). The three categories and their corresponding modes are: 1) General (binary, ascii and data) files - 'NORMAL' mode 2) Core image (save) files - 'SAVE' mode 3) FORTRAN IV load modules - 'LOAD' mode 4) System overlays - 'OFFSET' mode
March 1977 Page 8 FUTIL - OS/8 File UTILity program INTRODUCTION: The actual operation of the program for each of these modes is as follows: 'NORMAL' The high order 7 bits of the 15 bit address are added to the current block number to get the actual block number. The low 8 bits of the 15 bit address are used to specify the desired word within that block. 'SAVE' The file to be examined must be set up by a 'FILE' command. "Block" numbers are used to specifiy an overlay number (future MACREL/LINK support) and must be exactly zero ("0") for files without overlays (generated by the monitor "SAVE" command). The core segment data (pages and fields) from the file's CCB (core-control-block) is used to determine where on the device the desired word is to be found. This is done by first determining the correct block from the file's CCB and then using the low 8 bits of the address to specify the desired word within that block. Specifying a nonexistent address or overlay for one of the single-character (ODT) commands will cause an error. Specifying a nonexistent address or overlay for any of the word-type commands will cause the program to ignore the address and access no data. 'LOAD' The file to be examined must be set up by a 'FILE' command. Block number specifications are actually taken as overlay specifications and must be contained within the file. The information from the OIT (overlay-information-table) in the header block of the file is used to determine where on the device the desired word is to be found. Nonexistent addresses are handled the same way as for 'SAVE' mode. 'OFFSET' The 12 bit 'OFFSET' (which is set by the 'SET' command or by chaining with "/O=oooo" and examined by the 'SHOW' command) is subtracted from the low order 12 bits of the address and then the same arithmetic as with the 'NORMAL' mode is used. This mode is used mostly with system overlays whose start block number and actual loading address is known. By setting the 'OFFSET' to the loading address (which can only be a 12 bit number), the 12 bit "actual" addresses of the overlay can be used. The 'SAVE' and 'LOAD' modes are mentioned together throughout this writeup as MAPPED modes because their method of address translation uses a descriptor block from the file of interest to control access to the file in a non-contiguous manner.
March 1977 Page 9 FUTIL - OS/8 File UTILity program INTRODUCTION: NOTE on block number display For all access modes, the OS/8 "actual" block number for the block to be read is stored (for display) in the computer MQ register (if present). The value is stored before checking if the current block needs to be written. It is particularly useful for following the progress of the 'SCAN' command. Referencing words on the device: -------------------------------- The words on the OS/8 device are referenced by their <location> (often abbreviated as <l>). This <location> consists of an optional <block> or <overlay> number (which must be followed by a "." if present), and an <address> or <displacement>. The <block>/<overlay> number is a 12-bit number which must be in the range 0 thru 7776 (octal), or 4094 (decimal). Block number 7777 (or 4095, decimal) does not exist under OS/8, and the program will ignore this number. The <overlay> number is further limited to the number of overlays at a given address. Whenever the <block>/<overlay> part of the <location> is not used, the program will use the last specified value. The <address>/<displacement> is a 15 bit number (5 octal digits), but leading 0's need not be specified. Thus the forms are: <block>.<displacement> e.g. 1201.37524 or <overlay>.<address> e.g. 3.57633 or <address> e.g. 15721 or <displacement> e.g. 223 NOTE of caution on device handlers Neither this program nor the OS/8 handlers generally include checking for legal block numbers! It is simply assumed that all accesses to the device will be done after checking with the directory for legal file start blocks and lengths, which is the normal mode of operation under OS/8. This can have very interesting results with this program, e.g. the RK8/E handler, given a block number greater than 6257 (octal) on device RKA0, will simply continue on into device RKB0! Use some (or MUCH) caution! For the rest of this document, unless otherwise stated, block will mean <block> or <overlay> and address will mean <address> or
March 1977 Page 10 FUTIL - OS/8 File UTILity program INTRODUCTION: <displacement>, depending on usage. Therefore the definition will be: [block.]address = <location> = <l> Since these location references are numeric input, all of the characteristics described next can also be used when specifying locations. Numeric items (or numbers): --------------------------- Two switches are used by the program to allow the input of either octal, decimal or mixed numeric input where ever numeric input is used. Each new command line always resets the input mode to octal. The character "CTRL"-"D" (printed as "^D") switches the input mode for any following input to decimal. The character "CTRL"-"K" (printed as "^K") switches the input mode back to octal. These two switches may be located anywhere in numeric input. For example, when inputting a string of numbers, the input would be alternately decimal and octal if it were ^D100,^K100,^D200,^K200,^D300,^K300 Two other characters, double quote (""") and single quote ("'"), may be used for numeric input. The double quote functions the same way in this program as it does in PAL8--the 8-bit ascii value of the following character is used as a number. As with all character input, the special characters described earlier cannot be used. The single quote functions in a way similar to the way that the "TEXT" pseudo-op operates in PAL8--the following two characters are masked to 6-bits each and packed into a 12-bit word. There must always be exactly two characters following the single quote. If it is desired to pack one half of the word with a 6-bit 00, use the character "@". For example, a string equivalent to the file-name "PIP.SV" would be represented by the string 'PI,'P@,0,'SV Expressions may also be used for numeric input when enclosed in parentheses. The parenthesis pair "(" and ")" must surround the expression. When this is so, all the options of the 'EVAL' command are available for numeric input. For example, the contents of the switch register can be used for a number by the expression "(S)", or the current block number + 5 could be used by the expression "(B+5)". See the discussion of the 'EVAL' command for the other options available.
March 1977 Page 11 FUTIL - OS/8 File UTILity program INTRODUCTION: NOTE on expressions "(" and ")" must completely surround the expression! Neither digits nor the switch characters may be outside of the parentheses or an error will result. This is required because many of the non-alphabetic characters have multiple meanings (commands or operators) so the use of the parenthesis pair "(...)" provides the necessary context to remove ambiguity. Errors (and error messages): ---------------------------- Whenever the program recognizes an error of some type, it outputs out an error message to inform you what went wrong. The message tells both what went wrong and where in the command line the error was made. Depending on the setting of the 'ERROR' mode switch, either 'SHORT' or 'LONG' messages are output. The error messages have the forms: "?<ee> at <cc> <error message>" -'LONG' or "?<ee> at <cc>" -'SHORT' where <ee> is the error code, <cc> is the number of the column in the command line where the program stopped scanning and <error message> is the message itself. There are currently 45 error conditions with corresponding codes and messages to assist the user of this program. The error codes and their messages can be printed out by the 'SHOW' 'ERRORS' command. The 'ERROR' mode is set by the 'SET' command or by chaining with "/E" set. The error messages are swapped with the USR, but not in the normal manner, allowing write locked startup with the loss of the message text (see the section on program execution for more information).
March 1977 Page 12 FUTIL - OS/8 File UTILity program SINGLE CHARACTER (ODT-LIKE) COMMANDS: These commands allow the examination and modification of words on an OS/8 device in the same way that ODT allows the examination and modification of the memory in the computer. In all of the following commands where <n>--a numeric item--is specified, the operation of "closing" the location is to place the value of <n> into the word if it is open. If the current location is not open, or if <n> is not specified, no change takes place. Refer to the "Introduction to Programming" (DEC handbook) and the OS/8 Handbook sections on ODT for more information if needed. Note that (as mentioned previously) "[<n>]" with the following commands means that a numeric item may be optionally supplied. <l>/ Open & output the contents of location <l> in the current 'OUTPUT' mode. / Re-open the last location opened by one of these commands and output its contents in the current 'OUTPUT' mode. [<n>]# Close the current location, re-open it and output its contents in 'BCD' (3 digit binary-coded decimal). [<n>]$ (dollar sign) Close the current location, re-open it and output its contents in 'OS/8' ascii. [<n>]% Close the current location, re-open it and output its contents in 'BYTE' octal (8 bits with OS/8 packing). [<n>]& Close the current location, re-open it and output its contents in 'COS' format packed ascii. [<n>]: Close the current location, re-open it and output its contents in 'SIGNED' decimal. [<n>]< Close the current location, re-open it and output its contents in 'OCTAL'. [<n>]= Close the current location, re-open it and output its contents in 'UNSIGNED' decimal. [<n>]> Close the current location, re-open it and output its contents in 'PDP' (symbolic). [<n>]? Close the current location, re-open it and output its contents in 'DIRECTORY' format [negated DECIMAL, DATE and PACKED (ascii)]. [<n>]@ Close the current location, re-open it and output its contents in 'DATE' format ("mm/dd/yr", 2 digits each).
March 1977 Page 13 FUTIL - OS/8 File UTILity program SINGLE CHARACTER (ODT-LIKE) COMMANDS: [<n>][ Close the current location, re-open it and output its contents in 'ASCII'. [<n>]\ Close the current location, re-open it and output its contents in 'FPP' (symbolic). [<n>]] Close the current location, re-open it and output its contents in 'PACKED' ascii. [<n>]$ ("ALT-MODE" or "ESCAPE" keys) Close the current location, re-open it and type its contents as specified by the current 'FORMAT'. [<n>]"RETURN" Close the current location. [<n>]; Close the current location and open the next sequential location. Neither address nor contents are output, but one space is echoed. NOTE on use of ";" command The ";" command can be used to advance through addresses without outputting their value in octal when some other format is really more helpful. For example, when examining a directory, the file name and extension can be output Section of text corrupted in original file This is immediately followed by "\ " to separate the contents from the address. [<n>]"LINE-FEED" Close the current locaton, open and output the contents of the next sequential location in the current 'OUTPUT' mode. [<n>]! Close the current location, open and output the contents of the previous sequential location in the
March 1977 Page 14 FUTIL - OS/8 File UTILity program SINGLE CHARACTER (ODT-LIKE) COMMANDS: current 'OUTPUT' mode. [<n>]^ (up-arrow or caret) Close current location, open the location that would have been referenced if the contents were a PDP-8 memory reference instruction, and output the contents of the new location in the current 'OUTPUT' mode. Note: this command works like the stand-alone version of ODT, not like the OS/8 version. Even if bit 3 of the word (the indirect bit of a PDP-8 instruction) is a 1, this command will not do the equivalent of an indirect reference!!! [<n>]_ (back-arrow or underline) Close the current location, take its contents as an address, open that location and type out its contents in the current 'OUTPUT' mode. This operates as an indirect address into the current field would. The field currently being examined (the high octal digit of the 5 digit location) will not be changed by this operation. <l>+ Open the location <l> locations forward from the current location and output its contents in the current 'OUTPUT' mode. 15 bit arithmetic is used and the block part is ignored, so this will operate across field boundaries, i.e. within a 32K area. <l>- Open the location <l> locations backward from the current location and output its contents in the current 'OUTPUT' mode. Same restrictions as with the '+' command. The "current 'OUTPUT' mode" has been mentioned several times above. The program will output the contents of a location either as a four-digit octal number or as a four-digit octal number, two spaces and the "symbolic" representation ('PDP' or 'FPP') of the word. See the 'SET' and 'SHOW' commands as well as the following. "Symbolic" output formats: -------------------------- The "symbolic" typeout is in approximately the format that input to an assembler would need to be in order to generate the contents of the current location. It is assumed, of course, that these contents are either a PDP-8 or an FPP-12/8A instruction, depending on the output selected. If the word to be output is not an instruction, as is the case for the second word of all 2-word instructions (EAE and FPP), the decoding will obviously be meaningless.
March 1977 Page 15 FUTIL - OS/8 File UTILity program SINGLE CHARACTER (ODT-LIKE) COMMANDS: For PDP-8 instructions decoding into mnemonics is done for all memory reference instructions, for all legal operate instructions (including 8/E EAE instructions except for "SWAB"), for all 8/E processor, extended memory and memory parity IOTs, for teletype and high-speed paper-tape IOTs, for 8/E redundancy check option IOTs, for programmable real-time clock IOTs and for FPP IOTs. There are currently a total of 96 IOTs and space has been provided in the program for an additional 32 IOT codes and their mnemonics. These can be patched directly into the program using itself. The first word of each four-word entry is the exact IOT code (e.g. 6221 for "CDF 20"), followed by 3 words containing up to 6 packed ascii characters padded with trailing 0's. No attempt is made to decode any micro-coded IOTs. Either an exact match for the current contents will be found in the table or the program will output "IOT oooo" where oooo is the octal typeout of the low 9 bits of the code. The next free location in the table (which is in field 1) is pointed to by the contents of location 10000. The table is terminated by the first 0 for an IOT code, so additions must be contiguous and added directly at the current end of the table. For FPP instructions, the full FPP-8/A instruction set is decoded except for "IMUL", which is actually a mode dependent "LEA". For the data manipulation instructions, the op-code mnemonic is followed by a "#" for the long-indexed format, by a "%" for the indirect-indexed format and by a space for the base addressing format. For the indirect-indexed and base addressing formats, the operand address is output as "B+ooo" where ooo is the 3 digit octal value of the displacement (3 or 7 bits) multiplied by 3. These formats are those used by the RALF assembler. This is also true for "LEA" instructions (i.e. "LEAI" is decoded as "LEA%"). Both jump and load-truth instruction decoding is done as a single mnemonic whose last two characters indicate the specified condition. All instructions which use 2 words are decoded with an "*" in the location in the normal assempler format where the value of the second word would go. Index register number and "+" for auto-increment (if used) are also shown in the assembler format. Any combinations which are not in the FPP-8/A instruction definitions are output as "UNUSED". NOTE For both of these output formats, the use of the mapped access modes (and the 'OFFSET' mode for PDP decoding) allow the use of the "actual" addresses when decoding the instruction.
March 1977 Page 16 FUTIL - OS/8 File UTILity program WORD-TYPE COMMANDS: These commands are grouped by function, as follows: Group 1: DUMP type/list out the contents of one or more blocks. LIST type/list out the contents of one or more locations. MODIFY modify one or more locations. Group 2: WORD word search STRING string search SMASK set up string search mask Group 3: SET set up program switches & variables SHOW show settings of program switches & variables FILE look up file(s) on device WRITE write out current buffer SCAN scan for bad blocks REWIND move device to block 1 & reset directory segment EXIT exit to OS/8 (same as "CTRL"-"C") Group 4: EVAL evaluate a signed, double-precision expression. Command words may always be abbreviated to their first two characters, as with the Monitor and BUILD, and some of the commands and their options may also be abbreviated to only one letter. When this is true, the command forms given will include the one-letter form, and the option forms will give the one-letter form directly under the full word form. NOTE on command abbreviations In many cases, two or more words start with the same letter. In these cases, only one of these words may be abbreviated to one letter. The descriptions for each command include each of the possible forms of the command, with an example of that form following it on the same line.
March 1977 Page 17 FUTIL - OS/8 File UTILity program WORD-TYPE COMMANDS: Output formats -------------- The 'FORMAT' option is used to 'SET' up the output format for the "$" ('ALT-MODE' or 'ESCAPE') command (single-character) described earlier and the default format for the 'DUMP', 'LIST' and 'MODIFY' commands described below. The syntax of this command is shown with the other 'SET' commands but is described here to make the descriptions of the following three commands more understandable. The <format> may be one of the following: ASCII output each word as a single ascii character. A PACKED Output each word as two 6-bit trimmed and P packed ascii characters. This is the format of PAL8 TEXT strings. OS Output each word as 1 or 2 OS/8 packed ascii characters. The even address words output 1 character and the odd address words output 2 characters. COS Output each word as two 6-bit packed ascii C characters by adding a space (240 octal) to the contents of each 6-bit byte. This is the format of COS-300 data files and PAL12 SIXBIT strings. BYTE Output each word as 1 or 2 OS/8 packed bytes of 8 bits each as a 3-digit octal numbers. The even address words output 1 number and the odd address words output 2 numbers. UNSIGNED Output each word as an unsigned decimal U number. SIGNED Output each word as a signed decimal number. S OCTAL Output each word as a 4 digit octal number. O BCD Output each word as 3 bcd digits. The digits B 0 through 9 are followed by ":" (10), ";" (11), "<" (12), "=" (13), ">" (14) and "?" (15). PDP Output each word as an octal number, follow- FPP ed by 2 spaces and its mnemonic representa- tion, assuming it to be a PDP-8 or an FPP- 12/8a instruction. see the "symbolic" output
March 1977 Page 18 FUTIL - OS/8 File UTILity program WORD-TYPE COMMANDS: description. DIRECTORY Output each word in octal, decimal (negated before output), date and packed ascii formats. The 'FORMAT' is initialized to 'PACKED' ascii. The output from the 'DUMP' and 'LIST' commands for each of these formats is set up as follows: 1) At the beginning of each line the current location is output in <location> format with a 4 digit block number and a 5 digit address, both in octal, as: <block>.<address>: E.g. "1271.17205: "--location 17205(8) relative to block 1271(8). 2) The maximum number of words per line is set up as follows: A. The four character formats output 16 words per line with no extra characters. B. The five numeric formats output 8 words per line with 2 spaces between each number. C. The "symbolic" and directory formats output 1 word per line. For 'LIST' with A or B, the first line may be shorter than succeeding lines to force the second and following address outputs to be even multiples of 10 (octal). DUMP ---- The 'DUMP' command is used to output one or more whole 256 word device blocks in the default or an optionally supplied format. This command has the following forms: DUMP [<format>] <block string> DUMP <block string> DU 100,200-213,250 D <block string> D (B)-(B+10),(S) DUMP <format> <block string> DU PA 212 D <format> <block string> D OS 514 where the optional <format> is one of those given for the 'FORMAT' option above, and the <block string> is one or more numeric items separated by ","s and "-"s. The "-" is used when it is desired to dump a group of blocks, and is used as
March 1977 Page 19 FUTIL - OS/8 File UTILity program WORD-TYPE COMMANDS: <start block>-<end block> the "," is used to separate single blocks or groups of blocks if there is more than one per line. NOTE on mapped modes When in a mapped ('SAVE' or 'LOAD') mode, the 'DUMP' command cannot dump any block except the block containing location 0. To eliminate the confusion that this would produce, the command will simply output an error message reminding the user that the proper command to use in a mapped mode is the 'LIST' command. The output from the 'DUMP' command is sent to the 'LDEV' (list device), which can be either the console teletype or the line-printer handler configured into your system. See the 'SET' command for setting the list device and the miscellaneous information section for device usage information. LIST ---- The 'LIST' command is used to output the contents of one or more words on the device in the default or an optionally supplied format. This command has the following forms: LIST [<format>] <location string> LIST <location string> LI 123.200-517,200.0 L <location string> L 312.10-17,100-117,176 LIST <format> <location string> LI UN 200-227 L <format> <location string> L SY 200-277 where the optional <format> is one of those given for the 'FORMAT' option above, and the <location string> is one or more <location>s, separated by ","s. When it is desired to list a group of words, the "-" is used to separate the start and end addresses as [<block>.]<start address>[-<end address>] If the block part is not specified, the last block number specified to the program will be used. If an end address is specified, the start address is assumed to be in the same field as the end address (i.e.
March 1977 Page 20 FUTIL - OS/8 File UTILity program WORD-TYPE COMMANDS: the highest octal digit of the 5-digit address), so a maximum of 4096 words can be specified by each group. As with the 'DUMP' command, the output from the 'LIST' command is sent to the 'LDEV'. For more information see the last paragraph of the 'DUMP' command, the 'SET' command and the miscellaneous information section. MODIFY ------ The 'MODIFY' command allows a string of locations on the device to be changed in the easiest way. This is done by specifying the format of the input and letting the program do the work of storing the data properly. This command has the following forms: MODIFY [<format>] <location string> MODIFY <location string> MO 200.0-17,35-43 M <location string> M 32745-32777 MODIFY <format> <location string> MO PA 12342-12360 M <format> <location string> M AS 367.7261-7275 where the <location string> has exactly the same format as for the 'LIST' command and the <format> options are shown below. If the <format> is not specified (as with the first form), the program will pick the one of the formats below which corresponds to the current setting of the 'FORMAT' option. The corresponding formats are shown below. 'MODIFY' format 'FORMAT' setting and 'MODIFY' action. ASCII ASCII--one character of input is stored in A each word to be modified. PACKED PACKED--two characters of input are packed as P trimmed 6-bit characters, padded with trailing 00's. Control characters (those with codes less than 240 octal) are packed as a 6-bit 77 (flag) and the low-order 6-bits of the character. Note that this means that "@" is packed as a terminator (00) and that "?" is not unique. OS OS--three characters of input are packed into two words to be modified. When using this format, the start address must be even and the end address must be odd!!!
March 1977 Page 21 FUTIL - OS/8 File UTILity program WORD-TYPE COMMANDS: COS COS--a space (240 octal) is subtracted from C each character and then it is packed as 6-bit bytes. Control characters are handled as with 'PACKED' format. NUMERIC SIGNED & UNSIGNED decimal, BCD, OCTAL, BYTE, N PDP, FPP and DIRECTORY formats--the input is a string of numeric items which are stored one per 12 bit word. See the section on numeric items. Note that bcd, byte, directory and "symbolic" are not included, that decimal or octal input are determined by the "CTRL"-"D" and "CTRL"-"K" switches and that signed num- bers must be input enclosed in parentheses. E.G. 17,(-10), ^D200, (-^K312),40, (-^D35*129) For each location or group of locations specified by the <location string>, the program will prompt for the input by printing the start location in the same format as described under the output format options above. NOTE of caution The program always modifies exactly the number of words specified by each item in the <location string>! If you input extra characters for the character formats or extra numeric items for the numeric format, they will be ignored. If you input not enough characters or items, the rest of the words to be modified will be set to the 'FILLER' value (see the 'SET' command). The program will not output any message if either of these things take place!! This does, however, make it possible to fill from 1 to 16 blocks on a device with zero or some other value by specifying all the words to be filled in 'NUMERIC' format and then responding to the prompt with a single "(F)" (the value of the 'FILLER') and "RETURN". Input to the program is always terminated by a carriage- return ("RETURN"). It is therefore not possible to insert a carriage-return into a word using this command. All of the editing keys are available for use during input, therefore the "CTRL"-"C", "CTRL"-"R", "CTRL"-"P", "CTRL"-"U" and "RUBOUT" characters cannot be entered using this command either. For all of the character input formats, spaces and tabs in the input string are packed as they are seen. For numeric input, spaces are ignored and the numeric items must be separated by commas.
March 1977 Page 22 FUTIL - OS/8 File UTILity program WORD-TYPE COMMANDS: The command can always be aborted by "CTRL"-"P" if you change your mind before the "RETURN" key is pressed.
March 1977 Page 23 FUTIL - OS/8 File UTILity program WORD-TYPE COMMANDS: Search limits: -------------- There are two search commands in the program, the 'WORD' search and the 'STRING' search. They both search from a lower to an upper limit. The limits are either the 'LOWER' and 'UPPER' limits set by the 'SET' command (the default) or the limits set up by the "'FROM' <l>" (which overrides the 'LOWER' limit) and/or "'TO' <l>" (which overrides the 'UPPER' limit) clauses which can optionally follow the command word. Leaving out the block parts of either of the two temporary limits will cause the program to use the block part of the corresponding default limit set by the 'SET' command. When in a mapped ('SAVE' or 'LOAD') access mode, searching through nonexistent locations or overlays will never produce a match. Whenever a match is found, the program outputs the location where the match occurred, followed by the word or string that matched. NOTE on searching through overlays It is not possible to search through more than one overlay per search command. To do so would require different and separate handling of the "block" and "address" parts of the limits when in the mapped modes including the resetting of the "address" part. The result is that in the mapped modes the "block" parts are used to set the overlay to be searched (lower limit only) and only the "address" parts are used in the determination of the number of words to be searched. WORD (search) ------------- The 'WORD' search command is used to search for a word or words which, masked by the 'MASK' (which is set by the 'SET' command), will match the search word (also masked). This command has five options and therefore has the forms: WORD [UNEQ] [ABS] [MEM] [FROM <l>] [TO <l>] <n> WORD <n> WO 217 W <n> W (S) WORD UNEQUAL <n> W UN 0 WO U <n> WO U (C&377) WORD ABSOLUTE <n> WO AB 7402 W A <n> W A 7000 WORD MEMREF <n> WOR MEM 41
March 1977 Page 24 FUTIL - OS/8 File UTILity program WORD-TYPE COMMANDS: WO M <n> WO M 40 WORD FROM <l> <n> WO FR 213.0 2317 W F <l> <n> W F 1.35 (S) WORD TO <l> <n> W TO 213.345 1111 W T <l> <n> WORD T 6257.377 7777 ... and any combination and order of the above options... where <n> is the bit pattern being searched for, 'UNEQUAL' means that all words which are not equal to <n> under the mask do match, the temporary limits clause is as described above, 'ABSOLUTE' means that the location where the match occurred is to be output as an absolute block number and displacement rather than as a relative location, and 'MEMREF' means that only words whose high-order octal digit is 0 thru 5 (i.e. the PDP-8 memory reference op-codes) are allowed to match, independent of the setting of the 'MASK'. When you want to search for those words which reference a specific location, 'SET' the 'MASK' to 377 (octal) and then use the 'MEMREF' option. This will exclude all operate (op-code 7) and IOT (op-code 6) "instructions" from the output and can make it considerably easier to find the desired information (e.g. you will not output the location of every "CIA", 7041 octal, when you are looking for references to location 41 octal). NOTE on modifier priority 'UNEQUAL' has a higher priority than 'MEMREF', so first each word is tested under the mask for equal/'UNEQUAL' and if the specified condition is true, then the word is tested for the 'MEMREF' condition. STRING (search) --------------- The 'STRING' search command is used to search for a string of numbers (bit patterns) under an optional string mask. This command has four options and therefore has the forms: STRING [MASK] [ABS] [FROM <l>] [TO <l>] <numeric string> STRING <numeric string> ST 4557,0,0 STRING MASKED <numeric string> ST MA 4577,0,1203 ST M <numeric string> ST M 5566,0 STRING ABSOLUTE <numeric string> ST AB 'PI,'P@ ST A <numeric string> ST A "A,"B STRING FROM <l> <numeric string> STR FR 100 1,4000,2 STR F <l> <numeric string> ST F 123.4567 (S),(-S) STRING TO <l> <numeric string> STR T 7577 'ER,'RO,'R@
March 1977 Page 25 FUTIL - OS/8 File UTILity program WORD-TYPE COMMANDS: ST F <l> T <l> <numeric string> ST F 1.0 T 7.0 'FO,'TP ... and any combination and order of the above options... where the <numeric string> is simply a string of numeric items separated by commas, 'MASKED' specifies that the search is to be done under the string mask, 'ABSOLUTE' is as for the 'WORD' search, and the temporary limits clause is as described above. When the string mask is used, each item of the <numeric string> is masked by a separate mask word from the string mask. If the string mask is shorter than the search string, it is used in a circular fashion (the first word follows the last) as many times as necessary to mask all of the items of the search string. If the string mask is longer than the search string, the extra words are not used. This feature allows for very complex searches to be done. For example: Suppose it is desired to find all calls to a certain subroutine in a file and also see their arguments. This could be done as follows: FILE FUTIL --look up file to be searched FUTIL.SV 6070-6120^P --you stop typeout SE MODE SAVE --set access mode to mapped SMASK (-1),0,0 --set mask for 2 arguments per call ST M 4547,0,0 --search for 4547 and 2 dummies The output will give the address of the subroutine call (which requires an exact match due to the mask of 7777) and the contents of the two following words (which can be anything, since they are masked by 0). Using the mask specified above, a search could be made for an exact match, 2 "don't care words" and another exact match by simply specifying a search string with 4 arguments. The first item of the string mask will be used to mask both the first and the last items of the search string. This command can be particularly useful when trying to find certain kinds of references in programs for which no CREF listing (or perhaps no listing at all) is available. SMASK ----- The 'SMASK' command is used to set up the string mask. It has the following form: SMASK <numeric string> SM (-1),0,0,7000,0
March 1977 Page 26 FUTIL - OS/8 File UTILity program WORD-TYPE COMMANDS: where the <numeric string> is the same as for the 'STRING' search command above. The current contents of the string mask may be examined by the 'SHOW' command.
March 1977 Page 27 FUTIL - OS/8 File UTILity program WORD-TYPE COMMANDS: SET --- The 'SET' command is used to set up various switches and variables within the program. It has many options, each of which is the name of the switch or variable and is always followed by a word or number describing how it is to be set. The command has the following two forms: SET <option(s)> SE OU PDP ERR LONG MODE SAV S <option(s)> S LO 100.0 UP 123.377 LDEV LP where the options are as follows: OUTPUT OCTAL Set the output mode for the single- OUTPUT O character commands. Initialized to O PDP 'OCTAL'. O P OUT FPP O F ERROR SHORT Set the mode for error message output. E S The 'SHOW' 'ERRORS' command will out- E LONG put all error messages and codes for ERROR L 'SHORT' mode. Initialized to 'LONG'. Set to 'SHORT' by chaining with "/E" or with write locked system device. FORMAT <format> Set output format. The formats have been described previously. Initial- ized to 'PACKED' ascii. OFFSET <l> Set the offset to the low 12 bits of <l>. Initialized to 0. FILLER <n> Set the filler to the low 12 bits of <n>. Initialized to 0. LOWER <l> Set the lower search limit. Init1al- ized to 0.200 UPPER <l> Set the upper search limit. Initial- ized to 0.17577 DEVICE <device name> Set up the OS/8 device for access. The handler is fetched at this time. Initialized to "SYS" (device 01). Do not include ":" in <device name>. <device name> is an assigned or per- manent OS/8 mass storage device name. LDEV TTY Set up the device for 'DUMP', 'LIST'
March 1977 Page 28 FUTIL - OS/8 File UTILity program WORD-TYPE COMMANDS: LDEV LPT & 'SHOW ERR' commands. Initialized to 'TTY'. 'LDEV LPT' will fetch the "LPT" handler for your system. MODE NORMAL Set up the device access mode. MODE N These have been described MODE SAVE previously. Initialized to 'NORMAL'. MODE S set to 'SAVE' by chaining with "/S", MO LOAD to 'LOAD' by chaining with "/L" MO L and to 'OFFSET' by "/O=oooo". MO OFFSET MO O MASK <n> Set the 'WORD' search mask to the low M <n> 12 bits of <n>. Initialized to 7777. As many options as desired may be specified on one command line, separated by spaces. In the event of an error, none of the options past the point where the error occurred will have been set. If you have any question, use the 'SHOW' command. SHOW ---- The 'SHOW' command is used to output information on the current setting of all of the program switches and variables set by the 'SET' command and other information. The program outputs either words or numbers to best describe the current settings. As with the 'SET' command, as many of the options for this command as desired may be specified on a single command line, separated by spaces. This command has the form: SHOW <option(s)> SH BL CCB LOW UP ODT REL ABS where the <options> are as follows: BLOCK Output in octal the start block number B of the last file specified by the last 'FILE' command. CCB Output the core control block of the last C file specified by the 'FILE' command. If the file is not a 'SAVE' file, an error will occur. The start address of the file is output as a 5-digit octal number, the job status word (JSW) is output in octal, and the core segments are output as 5-digit octal addresses. When LINK files with overlays become available, the overlay information will be output as with
March 1977 Page 29 FUTIL - OS/8 File UTILity program WORD-TYPE COMMANDS: the 'HEADER' (next). HEADER Output the header block information for H the last file specified by the last 'FILE' command. If the file is not a 'LOAD' file, an error will occur. The start add- ress is output as a 5-digit octal number, followed by the next free address as a 5- digit octal number, the loader version number in octal and a message if Extended Precision is required. Then, for each level, a line is output with the number of overlays, the 5-digit start address, the relative start block and the length of the overlays for this level. ABSOLUTE Output the absolute location of the last A word accessed on the device in <location> format (a 4 digit octal block number, a "." and a 5-digit octal address). RELATIVE Output the relative location (what you R specified) of the last word accessed on the device in <l> format. ODT Output the relative location of the last word accessed by one of the special-char- acter commands in <l> format. LOWER Output the search lower limit in <l> format. UPPER Output the search upper limit in <l> format. FILLER Output the value of the filler in octal. MASK Output the 'WORD' search mask in octal. M SMASK Output the current contents of the 'STRING' search mask as a string of octal numbers. OFFSET Output the value of the offset in octal. MODE Output the name of the current setting of the device access mode switch ('NORMAL', 'SAVE', 'LOAD' or 'OFFSET'). DEVICE Output the OS/8 device name and number. OUTPUT Output the name of the current single- O character (ODT) command 'OUTPUT' mode (OCTAL, PDP or FPP).
March 1977 Page 30 FUTIL - OS/8 File UTILity program WORD-TYPE COMMANDS: FORMAT Output the name of the current format. F VERSION Output the current version number of FUTIL. ERRORS Output a complete list of all error codes E and their corresponding messages. Note: This list is output to the 'LDEV' (list device) so that it can be output using the "LPT" handler for your system. Note that Version number is also output with errors.
March 1977 Page 31 FUTIL - OS/8 File UTILity program WORD-TYPE COMMANDS: FILE ---- The 'FILE' command is used to locate files on the OS/8 device and to set up the start block of a file for the mapped access modes, 'SHOW' 'CCB', etc. This command has the forms: FILE <file name string> FI FUTIL PIP.SV F <file name string> F FORTRN MICRO.LD where the <file name string> is a string of one or more OS/8 file names, separated by spaces. The program assumes extensions of ".SV", ".LD" and null (in this order) when looking up the file. This can lead to a substantial amount of time when a large directory is searched three time for a file that does not exist. Specifying an extension will cause only one lookup attempt to be made. A null extension, if desired, may be specified by making the "." the last character of the file name. The program does one (or more) separate lookup(s) for each file name specified and outputs either <file name> ssss-eeee oooo (dddd) b.lll mm/dd/yr or <file name> ssss-eeee oooo (dddd) b.lll or <file name> LOOKUP FAILED where "ssss" is the start block of the file in octal, "eeee" is the last block of the file in octal, "oooo" is the length of the file in octal, "dddd" is the length of the file in decimal, "b.lll" is the block (segment) and location within that block of the first word of the file entry (the first two characters of the name) in the directory, and "mm/dd/yr" is the file date. If the directory does not contain the extra word required for the date or the date word of the file is 0, the second form with no date will be output rather than the first form. The "LOOKUP FAILED" message means either that the file name was not found on the device or that the device is a write-only device. The actual lookup operation is performed by the OS/8 USR, which is swapped as needed (see section on program execution). Since the USR keeps track of the current device once the first 'FILE' command is given, it will have the wrong directory in memory if the medium (tape or disk) is changed on the physical device. This can be solved one of two ways: 1) Use the 'REWIND' command to rewind the device being removed and reset the directory segment in the USR. 2) Do a 'SHOW ERRORS' and abort the output when the message output begins. This will have swapped out the USR. If messages are not available, use 1) or 3).
March 1977 Page 32 FUTIL - OS/8 File UTILity program WORD-TYPE COMMANDS: 3) Use EXIT or "CTRL"-"C" to return to OS/8 and then directly restart FUTIL with the 'START' command. This will have swapped out both error messages and USR from memory. Any of these methods should be followed by a 'SET' command to reset the 'DEVICE' (and the rest of the I/O switches in the program). The last file name specified that did not have a LOOKUP FAIL will be the file used in the mapped access modes, 'SHOW' 'CCB', etc. The program is initialized with no known file, so attempting to access any location in a mapped access mode or attempting to 'SHOW' 'CCB' or 'SHOW' 'HEADER' without giving a valid 'FILE' command will cause an error. WRITE ----- The 'WRITE' command is used to force the program to write out the block currently in memory. It has the form: WRITE [<block>] where the optional <block> overrides the default number of the block that was read to specify where the current block is to be written. This obviously dangerous operation does allow a limited amount of copying in a special situation, e.g. allowing a directory to be backed up by moving a copy to the end of the device (see the examples section) or copying a single block from one device to another by changing the 'DEVICE' and then doing a 'WRITE' (with or without an argument). Again, as stated in the section on accessing the device, caution must be used because attempting to write beyond the end of a device may not be checked by the handler. SCAN ---- The 'SCAN' command is used to do a rapid scan for read errors on the current 'DEVICE'. It has the form: SCAN <block string> SC 0-6257 where the <block string> is of the same form as for the 'DUMP' command. Each block is simply read. If an error occurs, it is reported as:
March 1977 Page 33 FUTIL - OS/8 File UTILity program WORD-TYPE COMMANDS: oooo BAD BLOCK where "oooo" is the block number in octal, and the scan continues. This is the only FUTIL command that will continue on a read error. Should the current block have been changed, and any other blocks be included in the scan, an implicit write will be attempted by FUTIL. An error on this implicit write will be reported and then the command will be aborted. This is the only time that this command will attempt a write. The command can then be repeated if it is desired and it will execute (only one implicit write attempt is ever made by FUTIL). NOTE on block number display The OS/8 "actual" block number for the block to be read is stored (for display) in the computer MQ register (if present). The value is stored before checking if the current block needs to be written. It is particularly useful for following the progress of this command. REWIND ------ The 'REWIND' command is used to move a tape back to block 1 and to reset the USR directory segment. It has the form: REWIND and must be terminated by the "RETURN" key. It causes a read of block 1 of the device and resets the directory segment key word in the USR (if in memory). Any subsequent 'FILE' command will cause the directory to be read. EXIT ---- The 'EXIT' command provides a method of return to OS/8 besides "CTRL"-"C". It has the form: EXIT and the rest of the line is ignored.
March 1977 Page 34 FUTIL - OS/8 File UTILity program WORD-TYPE COMMANDS: EVAL ---- The 'EVAL' command is used to evaluate a parenthesized expression of signed double-precision integers. It has the forms: EVAL <expression> EV S*^D4096+D E <expression> E B*400+L where the <expression> follows the normal rules for arithmetic expressions. Legal operators, in their order of precedence are: ( evaluate inner expression / signed division * signed multiplication - subtraction + addition & logical product ("and") ! logical sum ("or") ) expression end Besides 24 bit numeric input (which can be octal, decimal or mixed octal and decimal under the control of the "CTRL"-"D" and "CTRL"-"K" switches and ascii and packed ascii using """ and "'"), the following "variables" may be used: C current contents (of location "L"). L current location (15 bit, same value as is output by the 'SHOW' 'RELATIVE' command). B current block number (as for "L"). F contents of 'FILLER'. S contents of the console switch register. R the remainder of the last division or the high product of the last multiplication. 24 bits, the sign may not be correct. D contents of OS/8 Monitor "date" word. Overflow on addition, subtraction and multiplication are ignored, but trying to divide by 0 will cause an error. If no errors occur, the program evaluates the expression and types out the results in the form: "= oooooooo (sddddddd)"
March 1977 Page 35 FUTIL - OS/8 File UTILity program WORD-TYPE COMMANDS: where "oooooooo" is the double precision result in octal and "sddddddd" is the signed double precision result in decimal (the sign is either "-" or " ").
March 1977 Page 36 FUTIL - OS/8 File UTILity program ADDITIONAL EXAMPLES: These examples are to help provide an overview of the use of the program and to stimulate the thoughts of the user. They are not as well commented as the two examples on pages 1 and 2 because the desire is to show concepts of what can be done with the program rather than the mechanics of the operations. Should questions arise on the mechanics, it is suggested that those two examples and the discussions of the commands in question be reviewed. 1) While doing a "/S" transfer with PIP, it gives a read error in your file "SOURCE.PA". Attempting to read it with EDIT causes it to type "?0^C" and return to the Monitor. Find out what is wrong as follows: .R FUTIL FI SOURCE.PA --look up the file SOURCE.PA 0243-0351 0107 (0071) 2.005 08/30/72 SE MASK 0 LO 243.0 UP 351.377 --set up mask & limits W UNE 0 --search the file ?ee AT 08 FATAL READ ERROR --here is the problem [Note: "ee" may change with version, so is left out.] SH ABS --find out where it is ABS. LOC = 0271.00000 WR --attempt to clear error DU OS (B+L/400) --it worked, now dump it 0271.00000: ....^P --change your mind MOD NU 271.0-377 --zero the block to be sure 0271.00000: 0 -- of its state W UN FR 272.0 0 --check the rest of the file ^C --ok, now go fix the source This sequence can also be carried out using the SCAN command as follows: .FUT SOURCE.PA --use CCL to call & lookup SOURCE.PA 0243-0351 0107 (0071) 2.005 08/30/72 SCAN 243-351 --scan the area 0271 BAD BLOCK --here is the problem! 271.0/ ?ee AT 07 FATAL READ ERROR --get block with trouble
March 1977 Page 37 FUTIL - OS/8 File UTILity program ADDITIONAL EXAMPLES: WR --attempt to clear error DU OS (B+L/400) --it worked, now dump it 0271.00000: ....^P --change your mind MOD NU 271.0-377 --zero the block to be sure 0271.00000: 0 -- of its state WR --write out the block ^C --ok, now go fix the source If the error had been of some type other than a clearable error, the 'WR' command might also have failed. It might not be possible to fix the "SOURCE" file in this case. In either case, the data in the failing block may not be correct and may have to be corrected with the editor. NOTE on access The second 'WORD' search command will cause the block which has just been zeroed by the 'MODIFY' command to be written out. See the section on accessing the device for more information. 2) After using build to change your system, find out the device number for "DTA1": .R FUTIL SE DEV DTA1 --fetch the device handler SHOW DE DEVICE = DTA1 (06) --number is decimal 3) By accident you zero a DECtape directory which contains the only copy of a file you need. You have the PIP "/E" listing of the directory but only want to re-build it enough to get the wanted file. The name of the file is "LOST.FI": .R FUTIL SE DEV DTA1 --it was here EV ^D5+14+11+10+16+13+8+5 --lengths of all preceding = 00000122 ( 0000082) -- files EV ^D730-^K61-^D82-25 --rest of DECtape room = 00001076 ( 0000574)
March 1977 Page 38 FUTIL - OS/8 File UTILity program ADDITIONAL EXAMPLES: 1.0/ 7777 (-3) --now 3 files 4/ 7777 --1 extra word per entry 0001.00005\ 0000 'DU --set up a "DUMMY" file 0001.00006\ 7556 'MM -- over the old <EMPTY> 0001.00007\ 1752 'Y@ 0001.00010\ 3451 0 --a null extension 0001.00011\ 6234 (D) --put in today's date 0001.00012\ 4235 (-^D82) --length 0001.00013\ 5761 'LO --the desired file 0001.00014\ 3341 'ST 0001.00015\ 2371 0 0001.00016\ 1107 'FI --the extension 0001.00017\ 1366 (D) 0001.00020\ 3015 (-^D25) --its length 0001.00021\ 3415 0 --an <EMPTY> to end it 0001.00022\ 2713 (-^D574) --the rest of the tape WRITE --now write it out ^C -- & exit to use it The "LINE-FEED" key was used to advance through the words. The above example is exactly the same as hand calculating the required length of the "DUMMY" file and then doing the following sequence using PIP: .R PIP *DTA1:DUMMY</I=122 --enter the DUMMY file *DTA1:LOST.FI</I=31 --enter the LOST.FI *^C Note that the lengths of the files are specified in octal! 4) Search for the end of each page of text in the file "WRITE.UP". Since the file is an OS/8 ascii file, which has two characters packed in the low 8 bits of two words and a third character packed in the high 4 bits of both of the two words, the form-feed character (^L) may be packed as the third character in some cases. So it is necessary to search both through the low 8 bits of each word and through the high 4 bits of each pair of words. Do it as follows: .R FUTIL FI WRITE.UP WRITE.UP 0301-0437 S^P --typeout stopped SE MA 377 SE LO 301.0 UP 437.377 --char mask & limits set W A "^L --search for form-feed
March 1977 Page 39 FUTIL - OS/8 File UTILity program ADDITIONAL EXAMPLES: ....... typeout occurs here SMASK 7400,7400 --set up string mask ST M A ("^L*20),("^L*400) --search for 3rd char f-f ....... more typeout here --only even addresses are real -- parts of form-feed pair! In the string search, both the string and the data searched are "masked" by the string mask. 5) You just assembled and saved FUTIL but forgot to use the "/P" switch to ABSLDR. Fix the CCB (core-control-block) as follows: .ST --it's already in core FI FUTIL FUTIL.SV 0341-^P --stop output 341.1/ 6203 --the "CDF CIF" part & 0341.00002\ 6400 -- the address 0341.00003\ 0000 400 --change the JSW WR --write the new ccb SHOW CCB --check it this way CCB: SA = 06400, JSW = 0400 CORE^P --ok, output stopped 6) The CREF listing file for your source file is about 732 blocks long (just over one full DECtape). If you do want to CREF the file onto a DECtape, you must do it either with the "/X" (don't process literals) switch or else you could use FUTIL to set up the directory with 735 blocks (by starting at block 2) as follows: .R PIP *DTA1:</Z --zero the directory *^C .R FUTIL SE DEV DTA1 -- * * see WARNING below * * 1.1/ 0007 2 --change first block number 6/ 6446 (C-5) --5 more blocks WR --write it out ^C --now CREF it....
March 1977 Page 40 FUTIL - OS/8 File UTILity program ADDITIONAL EXAMPLES: * * * * WARNING! * * * * Do not copy files onto a device that has been fixed this way with FOTP (COPY command) because it writes out a directory of six blocks after the transfers are finished and this will zap blocks 2 through 6 (the first 5 blocks of the first file) after the copy is done! PIP and other processors do not monkey around with the directory and will handle this correctly 7) Something is extremely flaky in your system and you have been loosing your directory repeatedly. After fixing it up with both PIP and FUTIL, you want to just back it up while you generate your output files onto another device. Since your system device has a total of 6260 (octal) blocks (an RK8E) you back up the directory as follows: .FUTIL/X -defeat remembrance 1.0/ 7714 WR 6251 --transfer blocks up by 2.0/ 7740 WR 6252 -- 6250 blocks. 3.0/ 7770 WR 6253 4.0/ 0000 3.2/ 0000 --block 3 was last, so ^C -- all done Shortly after this, everything crashes totally, i.e. directory smashed, system gone from disk. Rebooting from your trusty DECtape you use PIP to restore the system area and then use FUTIL to restore the directory: .R FUTIL --No CCL from DECtape! SET DEV RKA0 --load non-system device 6251.0/ 7714 WR 1 --transfer by 6250 blocks 6252.0/ 7740 WR 2 -- the other way 6253.0/ 7770 WR 3 --the last one SCAN 0-6250 --do a SCAN for good luck 8) During a SCAN of a device a bad block is found in an important data file and you would like to know just how far the read of that block really succeeded (e.g. on a DECtape, the type of error will determine whether the read will abort immediately or wait until the end of the physical block). The following commands assume that the block number is "bbbb" and set the input/output buffer in FUTIL to zeros before doing the read: bbbb.0/ ?ee AT 07 FATAL READ ERROR --do read to set up
March 1977 Page 41 FUTIL - OS/8 File UTILity program ADDITIONAL EXAMPLES: MOD NUM 0-377 bbbb.00000: 0 --set whole buffer to 0 SET DEV same --set to device now in use / ?ee AT 01 FATAL READ ERROR --force the read again DUMP OC bbbb --dump & examine the block This example makes use of the fact that changing the DEVICE resets the status of the buffer without changing its contents. This status includes the block number known and the <something-changed> flag. Therefore the next access to the block causes the block to be re-read without attempting to write it out. Following the second error, as much as possible of the block will have been read into memory and can now be examined for non-zero values (assuming that the data itself was not all zeros!). If the read terminated before the end of the block, there should be an obvious separation between the zero and non-zero values. 9) Your system has a line printer which can output 132 characters per line and 68 lines per page and you would like to change PAL8 and CREF to make use of this to use less paper. Allowing two lines at the bottom of the page, the lines per page should be set to 66 (call this "nl"). Three changes need to be made to PAL8 to change the global number of lines per page (nl), the number of items per column of the symbol table (-nl+1) and the number of symbols per page (3*[nl-1]). One change needs to be made to CREF to change the number of lines per page (nl) and three changes need to be made to change the number of items per line of cross references. Since CREF uses 10 characters for the symbol name and 6 characters per line number, 19 references can comfortably fit on one line (19*6+10 = 124). The following changes to these two processors will increase the number of lines per page and the number of items per line in the cross-reference outputs and then update the dates of the two processors in the directory: .FUT PAL8/S -- * * SEE NOTE BELOW * * PAL8.SV 0200-0217 0020 (0016) 1.057 04/03/76 1104/ 0070 ^D66 --global lines per page 1256/ 7711 (-^D65) --symbol table column size 1273/ 0245 (3*^D65) --symbols per page FILE CREF -- * * SEE NOTE BELOW * * CREF.SV 0220-0234 0015 (0013) 1.065 01/18/74 2564/ 7704 (-^D66) --lines per page as above
March 1977 Page 42 FUTIL - OS/8 File UTILity program ADDITIONAL EXAMPLES: 2017/ 1102 1366> TAD 2166 --change instructions here 2132/ 1102 1366> TAD 2166 -- and here to get new 2166/ 0077 (-^D19) -- references per line SET MODE NORM --reset access mode 1.(57+4)/ 2036 (D) --change dates of PAL8 (65+4)/ 624 (D) -- and CREF. WRITE --output the last changes Location 2166 was not used previous to this patch. Note that the first reference to the word in CREF will cause the last block that was modified in PAL8 to be written out. Similarly, the first reference to the directory will cause the last block that was modified in CREF to be written out. NOTE on versions of PAL8 and CREF These patches were empirically determined and applied to PAL8 V9H and CREF V3C. They have been applied to some other versions of both processors and may be correct for all versions of PAL8 V9 and CREF V3. USE THESE WITH CAUTION! These patches were determined by Dennis McGhie for use with his program called VLIST, which uses PLOT mode on a Versatec printer/plotter to output optionally higher density characters and to implement lower case characters for printers without that option. This example is provided partly to document these changes for others who might find them useful. Dennis was not able to decode the code used in the PAL8 symbol table output routine well enough to be able to allow for more columns in the symbol table output. I would be glad to update this example to include this information if is possible.
March 1977 Page 43 FUTIL - OS/8 File UTILity program MISCELLANEOUS INFORMATION: Assembling, loading & CREFing the program: ------------------------------------------ Five files are provided with the release of FUTIL, the core image, source, writeup and help files of FUTIL and the source file for the patches to CCL to add the FUTIL command. This last source file (named FUTCCL.PA) contains the documentation for its implementation. Remember that after patching CCL.SV the command "R CCL" must be given to update the Monitor command tables with the new command. Assemble and load the program as follows: .R PAL8 *FUTIL,FUTIL<FUTIL/L/P=6400$ .SA ... FUTIL The binary file requires about 35 blocks, the listing file about 665 blocks and the cref listing about 880 blocks. Crefing the listing requires either "/M" or "/X" for CREF V3. Program execution and memory allocation: ---------------------------------------- The start address (as seen above) is 06400. When the program is started here, it resets the internal CCB buffer, resets the start address to 00200, attempts to write out the error messages (resetting the 'ERROR' mode control if unsuccessful) and jumps to 00200. If, for some reason, it is desired to manually re-start the program after it has been loaded, it can be re-started at 00200. Chaining support has been added to FUTIL to allow the addition of a CCL command to call FUTIL, perform an optional device and/or file setup, and optionally set 'SHORT' error mode and/or one of the three access modes other than 'NORMAL'. After CCL has been patched with a small source file which accompanies the FUTIL source, the following command is added: F[UTIL] [dev:][file[.ex]] [/E] [<access mode>] where only the first character is required (but any others specified must be correct), the optional device defaults to DSK if a file name is included but otherwise is SYS, the optional file name will cause a 'FILE' command to be performed as the last setup operation (in which case the extension will default to all three normal defaults), the optional "/E" sets the 'ERROR' mode to 'SHORT' (to remove the need to swap the USR) and the optional <access mode> specification can be one of the following--
March 1977 Page 44 FUTIL - OS/8 File UTILity program MISCELLANEOUS INFORMATION: /L Set the mode to 'LOAD' and set the default extension to use only ".LD". /O=oooo Set the mode to 'OFFSET' and set the 'OFFSET' to "oooo". /S Set the mode to 'SAVE' and set the default extension to use only ".SV". The error messages are swapped with the USR, but not in the normal manner, allowing write locked startup with the loss of the message text. When the program starts execution, it writes the messages onto the system device in the same area used by the USR in swapping. Once this has been done, the USR or error messages need only be read into memory, as needed. In the case where it is not possible to write on the system device, i.e. it is write locked, the messages are discarded, 'SHORT' mode is set permanently and execution continues without a hitch. Similarly, should an error occur when reading the messages, 'SHORT' mode is set permanently and an error is given to warn that this has happened (with no message, of course!). The program uses almost all of the available memory in an 8K PDP-8. It is allocated as follows: 00000-06240 program proper 06240-06577 buffer for arguments 06400-06577 -- once only code for chaining -- 06600-07177 LPT: handler area, 2 pages 07277-07577 device handler area, 2 pages 10000-11777 usr area & error messages (swapped) 12000-12177 ccb/header input and test 12200-15240 text strings, lists 15240-16177+ string mask, command buffers, p.d.l. 16400-16777 LPT: buffer, 2 pages 17000-17177 CCB buffer, 1 page 17200-17577 I/O buffer, 2 pages The buffer for arguments in field 0 is defined long enough to store 45 numeric string items. The string mask buffer, in field 1, is 66 words long, and the command buffer, also in field 1, is 140 characters long. These lengths were chosen in anticipation of input from console devices with up to 132 characters per line. No checking of any kind is done to protect against overflow of any of these buffers under the assumption that these buffers are large enough for any reasonable input to this program, however, the arrangement of the buffers is set up in such a way that the most valuable data is the farthest distance from a variable buffer. The push-down-list (p.d.l.) buffer uses the area in field 1 from the end of the command buffer (approximately location 15540) to the beginning of the LPT: buffer (location 16400). This should
March 1977 Page 45 FUTIL - OS/8 File UTILity program MISCELLANEOUS INFORMATION: provide ample room for any expression able to fit on one line. Again, no checking to prevent overflow is done. List device output: ------------------- The list device output for the 'DUMP', 'LIST' and 'SHOW' 'ERRORS' commands has been implemented for the single purpose of speeding up the output from these commands for immediate viewing. As a result, a very simplified approach has been taken which was not designed for general file-type output. As a result of this approach, the output buffer is dumped to the line-printer handler at the end of every line of output. The characters in the buffer are stored one per word and the buffer is padded with 0's before the handler is called (so the handler should ignore nulls!). The block number in the handler call is set to 7777 (octal) and is never changed, for the specific purpose of disallowing output to a mass storage device through a Monitor "ASSIGN" command. [Note: since 0 is not a legal device length, no device can have more than 4095 blocks and there is no block 7777 under OS/8! However BE WARNED (!!!!!!!) that most handlers have no bad block number protection built in!] Implementation notes: --------------------- This program, in its current state, reflects about 10 years of on and off development. Although a few of the commands have changed and many new features have been added (requiring at least 2 global re-structurings), the general philosophy remains the same--a command driven debugging tool with two major command types and as many features to aid debugging as could be crammed into the available space. FUTIL is largely a table driven processor, using the "sort-and-branch" table idea to perform one- and two-character table lookups. Since compute speed is generally not important, this method is used even when simply checking characters for validity because it reduces the amount of code in field 0 (at the expense of space in field 1, which is not full). Some of the execution routines make use of the "sort-and-branch" routine pointers to index into a third table of some sort. This, for example, allows a single small routine of about 25 words to handle all 13 of the special characters (ODT commands) which replace the current contents of the open location with an optional new value and then output the current contents in a specified format. The program proper is in field 0 with some space for handlers and a single temporary buffer. All of the lists for the
March 1977 Page 46 FUTIL - OS/8 File UTILity program MISCELLANEOUS INFORMATION: "sort-and-branch" routine, text for output, instruction mnemonics and error messages are in field 1 with a small amount of code. The major buffers are also in field 1. The command input routine collects characters from the console device through a subroutine which handles case conversion, rubouts, line re-echo and line erase. They are then checked for the set of terminator characters (all of the ODT-like command characters fall into this class) and if not terminators, they are stored directly into the line buffer. Due the fact that most of these terminator characters may also be arithmetic operators, depending of their context (inside or outside of parentheses, on a line that does or does not begin with a "word"), the context of each candidate terminator must be checked by doing a scan of the line buffer to determine if the first character in the buffer is alphabetic (a "word") and, if not, whether the character is inside of a parenthesized expression or is a quoted character. If any of these conditions are true, the character is not a terminator so it is also put into the line buffer and input continues. If none are true, the line buffer is terminated with a carriage return (removing all of the special case checking that would be needed later) and the terminator character is acted upon (because it is really a command character). The program is designed in a fairly modular fashion, with a hierarchy of actions. At the top level is the command input routine (described above). Immediately beneath this routine are the special-character (ODT) command execution routines, followed by the word command execution routines. These routines are not at two different levels due to the logic of the routines themselves but rather due to the fact that the addresses used by the ODT commands are passed to the level of the word commands but not the other way (note the 'SHOW' commands 'ODT' and 'REL'). This is due to the fact that ODT is required to allow a return to the last location opened by an ODT command by simply entering a "/". These call numerous support subroutines to fetch arguments (including evaluation of expressions), get a word, etc. All commands (except for 'SCAN') then call the mapping routine to do whatever address translation is required and it then calls the I/O manager which pages the device as necessary. 'SCAN' never does mapping and so calls the I/O manager directly. Other exceptions are the'FILE', 'SET' and 'SHOW' commands, which are not directly related to device access but are required to make the program useable. These commands, by their very nature, require a significant amount of code that is not able to made common with the routines which are related to device access. The hierarchy described above is maintained fairly strictly throughout the program and has allowed many new features to be added with sometimes trivial amounts of code. For example, when overlay support was added, only the 'SET' and 'SHOW' commands and the mapper needed to be changed and then the <block> part of the address was just re-defined as <overlay> and none of the command routines or support subroutines knew that anything had changed. Adding the COS formatting
March 1977 Page 47 FUTIL - OS/8 File UTILity program MISCELLANEOUS INFORMATION: required adding 1 or 2 words to each of 6 format tables in field 1 and then adding new packing and unpacking routines in field 0. Adding the SCAN command required the addition of 1 word each to 2 lists, 5 words of initialization code, a new subroutine and the separation of the device access routine into two levels (mapping and I/O manager). Again, in both of these cases none of the rest of the program was changed.
March 1977 Page 48 FUTIL - OS/8 File UTILity program COMMAND SUMMARY: SINGLE-CHARACTER commands: ([<n>] = optional <item>) [<l>]/ <l>+ <l>- [<n>] with # $ : % & < = > ? @ [ \ ] $ ("ALT-MODE") "RETURN" ; "LINE-FEED" ! ^ _ WORD-TYPE commands: (And modifiers, many of which are optional) ASCII PACKED OS COS UNSIGNED SIGNED BCD BYTE OCTAL PDP FPP DIR DUMP [<format>] <block string> ([<format>]s above) LIST [<format>] <location string> ([<format>]s above) MODIFY [<format>] <location string> ([<format>]s below) ASCII PACKED OS COS NUMERIC WORD <option(s)> <n> UNEQUAL ABSOLUTE MEMREF FROM <l> TO <l> STRING <option(s)> <number string> MASKED ABSOLUTE FROM <l> TO <l> SMASK <number string> e.g. 1,34,0,7700,0,(-1),377 SET <option> <setting> OUTPUT OCTAL SYMBOLIC ERROR LONG SHORT FORMAT <format> OFFSET <l> LOWER <l> UPPER <l> DEVICE <device name> LDEV TTY LPT MODE NORMAL SAVE LOAD OFFSET MASK <n> FILLER <n> SHOW <option(s)> BLOCK CCB ABSOLUTE RELATIVE ODT LOWER UPPER MASK SMASK OFFSET MODE DEVICE OUTPUT FORMAT HEADER FILLER VERSION ERRORS FILE <file name(s)> WRITE [<block>] SCAN <block string> REWIND EXIT EVAL <expression> e.g. (1!(S+^D17))*^K15+(C&7600) ! & + - * / ( ) C L S B R D Numeric input: ^D ^K <digits> "<1 character> '<2 characters> (...all eval options...) Control characters: ^P ^C ^U ^R RUBOUT
March 1977 Page 49 FUTIL - OS/8 File UTILity program SINGLE-CHARACTER COMMAND OUTPUT FORMAT SUMMARY: ([<n>] = optional numeric item) Output in octal or octal & "symbolic" (PDP or FPP): <l>/ / [<n>]"LINE-FEED" [<n>]! [<n>]^ [<n>]_ <l>+ <l>- Output in a specified format: [<N>]# BCD [<n>]$ OS/8 ascii [<n>]: SIGNED decimal [<n>]% BYTE octal [<n>]& COS format packed ascii [<n>]< OCTAL [<n>]= UNSIGNED decimal [<n>]> PDP "symbolic" [<n>]? DIRECTORY [<n>]@ "DATE" format [<n>][ ASCII [<n>]\ FPP "symbolic" [<n>]] PACKED ascii [<n>]$ ("ALT-MODE") as 'SET' by last 'FORMAT' option (or "ESCAPE") No output: [<N>]"RETURN" [<n>];

Feel free to contact me, David Gesswein djg@pdp8online.com with any questions, comments on the web site, or if you have related equipment, documentation, software etc. you are willing to part with.  I am interested in anything PDP-8 related, computers, peripherals used with them, DEC or third party, or documentation. 

PDP-8 Home Page   PDP-8 Site Map   PDP-8 Site Search