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 DEPARTMENT OF ANESTHESIA STANFORD MEDICAL CENTER STANFORD, CALIF. 94305 FRELAN ASSOCIATES P.O. BOX 298 MENLO PARK, CALIF. 94025 FUTIL - OS/8 FILE UTILITY PROGRAM JAN. 17, 1973 PAGE I ACKNOWLEDGEMENT I WANT TO ESPECIALLY THANK SEVERAL PEOPLE WHO READ THIS WRITEUP AND COMMENTED ON IT AND THE PROGRAM. TIM CLARKE, OF THE DIVISION OF CARDIOVASCULAR SURGERY, REVIEWED THIS WRITEUP MANY TIMES DURING ITS GROWTH. JIM WARREN, ALSO OF FRELAN ASSOCIATES, AND JOHN TUBBS, OF THE DEPARTMENT OF PREVENTIVE MEDICINE, EACH MADE MANY HELPFUL COMMENTS ON THE WRITEUP. DENNIS MCGHIE, ALSO OF THE DIVISION OF CARDIOVASCULAR SURGERY, MADE SEVERAL SUGGEST- IONS ON POSSIBLE ADDITIONS TO THE PROGRAM, THE ERROR MESSAGES IN PARTICULAR. ALSO NOT TO BE FORGOTTEN ARE SEVERAL OF MY OTHER FRIENDS WHO MADE COMMENTS AND SUGGESTIONS. FUTIL - OS/8 FILE UTILITY PROGRAM JAN. 17, 1973 PAGE II TABLE OF CONTENTS: ------------------ INTRODUCTION . . . . . . . . . . . . . . . . . . . . . 1 SPECIAL CHARACTERS USED IN THIS WRITEUP . . . 1 SPECIAL CHARACTERS USED IN FUTIL . . . . . . . 1 REFERENCING WORDS ON THE DEVICE . . . . . . . 2 NUMERIC ITEMS (OR NUMBERS) . . . . . . . . . . 2 ERRORS (AND ERROR MESSAGES). . . . . . . . . . 3 ACCESS METHOD . . . . . . . . . . . . . . . . 4 SINGLE CHARACTER (ODT-LIKE) COMMANDS . . . . . . . . . 6 "SYMBOLIC" OUTPUT FORMAT . . . . . . . . . . . 7 WORD-TYPE COMMANDS . . . . . . . . . . . . . . . . . . 8 FORMAT . . . . . . . . . . . . . . . . . . . . 9 DUMP . . . . . . . . . . . . . . . . . . . . . 10 LIST . . . . . . . . . . . . . . . . . . . . . 10 MODIFY . . . . . . . . . . . . . . . . . . . . 11 WORD (SEARCH) . . . . . . . . . . . . . . . . 13 STRING (SEARCH) . . . . . . . . . . . . . . . 14 SMASK . . . . . . . . . . . . . . . . . . . . 15 OPTION . . . . . . . . . . . . . . . . . . . . 16 SHOW . . . . . . . . . . . . . . . . . . . . . 17 FILE . . . . . . . . . . . . . . . . . . . . . 18 WRITE . . . . . . . . . . . . . . . . . . . . 20 REWIND . . . . . . . . . . . . . . . . . . . . 20 EVAL . . . . . . . . . . . . . . . . . . . . . 21 ADDITIONAL EXAMPLES . . . . . . . . . . . . . . . . . 22 MISCELLANEOUS INFORMATION . . . . . . . . . . . . . . 25 ASSEMBLING, LOADING & CREFING THE PROGRAM . . 25 START ADDRESS AND CORE ALLOCATION . . . . . . 25 LIST DEVICE OUTPUT . . . . . . . . . . . . . . 26 COMMAND SUMMARY . . . . . . . . . . . . . . . . . . . 27 FUTIL - OS/8 FILE UTILITY PROGRAM JAN. 17, 1973 PAGE 1 INTRODUCTION: ------------- THE PURPOSE OF FUTIL IS TO ENABLE A USER TO EXAMINE AND MODIFY OS/8 MASS STORAGE DEVICES FROM THE TELETYPE. EIGHT TYPE- OUT FORMATS ALLOW EASY EXAMINATION OF WORDS ON THE DEVICE IN THEIR MOST MEANINGFUL FORMAT. THE COMMAND SET OF FUTIL IS DIVIDED INTO TWO GROUPS OF COMMANDS. 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. 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 VAR- IABLES WITHIN THE PROGRAM, SHOWING THEIR SETTINGS AND VALUES, ETC. SPECIAL CHARACTERS USED IN THIS WRITEUP: ---------------------------------------- TO HELP REDUCE THE CONFUSION BROUGHT ABOUT BY THE FACT THAT THIS WRITEUP IS COMPLETELY IN UPPER CASE LETTERS, THE CHARACTERS SINGLE QUOTE ('), DOUBLE QUOTE (") 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' COMMAND IS THE COMMAND THAT SETS 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 SQUARE BRACKETS ARE USED TO SURROUND THE NAME OF A TYPE OF ITEM, E.G. "[N]" MEANS THAT A NUMERIC ITEM IS TO BE USED. SPECIAL CHARACTERS USED IN FUTIL: ---------------------------------- SEVERAL CHARACTERS, WHEN TYPED, 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 ALL SYSTEM PROGRAMS). FUTIL - OS/8 FILE UTILITY PROGRAM JAN. 17, 1973 PAGE 2 DURING THE TIME THAT YOU ARE DOING TELETYPE 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"-"G" (WHICH PRINTS "^G"). 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"-"G" IS THE SAME AS THAT OF THE "LINE-FEED" KEY FOR THE MONITOR AND COMMAND DECODER (THIS HAD TO BE DONE DUE TO THE FACT THAT "LINE-FEED" IS USED FOR OTHER THINGS IN THIS PROGRAM). 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 BEGINS WITH A COMMAND WORD OR IF THEY ARE EMBEDDED WITHIN EXPRESSIONS. THE CARRIAGE RETURN ALWAYS BEGINS COMMAND EXECUTION, AND IS THE TERMINATOR FOR ALL WORD-TYPE COMMAND LINES. REFERENCING WORDS ON THE DEVICE: -------------------------------- THE WORDS ON THE OS/8 DEVICE ARE REFERENCED BY THEIR [LOCATION] (SOMETIMES ABBREVIATED AS [L]). THIS [LOCATION] CONSISTS OF AN OPTIONAL [BLOCK] NUMBER (WHICH IS FOLLOWED BY A "." IF PRESENT), AND AN [ADDRESS]. THE [BLOCK] 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. WHENEVER THE BLOCK PART OF THE LOCATION IS NOT USED, THE PROGRAM WILL USE THE LAST SPECIFIED BLOCK NUMBER. THE [ADDRESS] IS A 15 BIT NUMBER (5 OCTAL DIGITS), BUT LEADING 0'S NEED NOT BE SPECIFIED. THUS THE TWO FORMS ARE: [BLOCK].[ADDRESS] E.G. 1201.37524 OR [ADDRESS] E.G. 157 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- FUTIL - OS/8 FILE UTILITY PROGRAM JAN. 17, 1973 PAGE 3 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 FOLLOW- ING 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 (PAGE 21). NOTE!! "(" AND ")" MUST COMPLETELY SURROUND THE EXPRES- SION! NEITHER DIGITS NOR THE SWITCH CHARACTERS MAY BE OUTSIDE OF THE PARENTHESES OR AN ERROR WILL RESULT. ERRORS (AND ERROR MESSAGES): ---------------------------- WHENEVER THE PROGRAM RECOGNIZES AN ERROR OF SOME TYPE, IT TYPES 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 'LONG' OR 'SHORT' MESSAGES ARE OUTPUT. THE 'LONG' MESSAGE HAS THE FORM: FUTIL - OS/8 FILE UTILITY PROGRAM JAN. 17, 1973 PAGE 4 "? AT [CC] [ERROR MESSAGE]" WHERE [CC] IS THE NUMBER OF THE COLUMN IN THE COMMAND LINE WHERE THE PROGRAM STOPPED SCANNING AND [ERROR MESSAGE] IS THE MESSAGE ITSELF. THE 'SHORT' MESSAGE HAS THE FORM: "?[EE] AT [CC]" WHERE [EE] IS THE ERROR CODE AND [CC] IS AS ABOVE. THE ERROR CODES AND THEIR MESSAGES CAN BE PRINTED OUT BY THE 'SHOW' 'ERRORS' COMMAND. THE 'ERROR' MODE IS SET BY THE 'OPTION' COMMAND. 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, A 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. 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. IF THE WORDS WITHIN SOME BLOCK ARE CHANGED ACCIDENTALLY, THE "SOMETHING-CHANGED" FLAG CAN BE RESET BY USING THE 'OPTION' COMMAND TO RESET THE 'DEVICE' (DESCRIBED FURTHER ALONG IN THIS WRITEUP) TO THE SAME DEVICE CURRENTLY BEING USED. THIS WILL RESET THE FLAG, THE CURRENT BLOCK IN MEMORY, AND THE FILE START BLOCK AND CORE-CONTROL-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. EVERYTHING STORED ON AN OS/8 MASS-STORAGE DEVICE FALLS INTO ONE OF THREE CATEGORIES. THE PROGRAM HAS THREE CORRES- PONDING MODES FOR ACCESSING THE DEVICE. THE CURRENT 'MODE' OF THE PROGRAM CAN BE SET BY THE 'OPTION' COMMAND AND EXAMINED BY THE 'SHOW' COMMAND (TO BE DESCRIBED LATER). FUTIL - OS/8 FILE UTILITY PROGRAM JAN. 17, 1973 PAGE 5 THE THREE CATEGORIES AND THEIR CORRESPONDING MODES ARE: 1) GENERAL (BINARY, ASCII AND DATA) FILES - 'NORMAL' MODE 2) CORE IMAGE (SAVE) FILES - 'FILE' MODE 3) SYSTEM OVERLAYS - 'OFFSET' MODE 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. 'FILE' THE FILE TO BE EXAMINED MUST BE SET UP BY A 'FILE' COMMAND. ALL BLOCK NUMBER SPECIFICATIONS ARE IGNORED AND THE BLOCK IS JAM SET TO THE START BLOCK OF THE FILE. 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 FOR ONE OF THE SINGLE-CHARACTER (ODT) COMMANDS WILL CAUSE AN ERROR. SPECIFYING A NONEXISTENT ADDRESS FOR ANY OF THE WORD-TYPE COMMANDS WILL CAUSE THE PROGRAM TO IGNORE THE ADDRESS AND ACCESS NO DATA. 'OFFSET' THE 12 BIT 'OFFSET' (WHICH IS SET BY THE 'OPTION' COMMAND 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. FUTIL - OS/8 FILE UTILITY PROGRAM JAN. 17, 1973 PAGE 6 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 EXAM- INATION 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) SECTION ON ODT FOR MORE INFORMATION IF NEEDED. [L]/ OPEN & TYPE OUT THE CONTENTS OF LOCATION [L] IN THE CURRENT 'OUTPUT' MODE. / RE-OPEN THE LAST LOCATION OPENED BY ONE OF THESE COMMANDS AND TYPE OUT ITS CONTENTS IN THE CURRENT 'OUTPUT' MODE. [N]< CLOSE THE CURRENT LOCATION, RE-OPEN IT AND TYPE OUT ITS CONTENTS IN 'SYMBOLIC'. [N]> CLOSE THE CURRENT LOCATION, RE-OPEN IT AND TYPE OUT ITS CONTENTS IN OCTAL. [N]$ ("ALT-MODE" OR "ESCAPE" KEYS) CLOSE THE CURRENT LOCATION, RE-OPEN IT AND TYPE ITS CONTENTS AS SPECIFIED BY THE LAST 'FORMAT' COMMAND. [N]: CLOSE THE CURRENT LOCATION, RE-OPEN IT & TYPE OUT ITS CONTENTS IN SIGNED DECIMAL. [N]"RETURN" CLOSE THE CURRENT LOCATION. [N]; CLOSE THE CURRENT LOCATION AND OPEN THE NEXT SEQUENTIAL LOCATION. NEITHER ADDRESS NOR CONTENTS ARE TYPED OUT, BUT TWO SPACES ARE ECHOED. FOR THE FOLLOWING COMMANDS, THE ADDRESS OF THE NEWLY OPENED LOCATION IS TYPED OUT BEFORE THE CONTENTS ARE TYPED. THIS ADDRESS IS COMPOSED OF THE 12 BIT BLOCK NUMBER (4 OCTAL DIGITS), A "." FOR A SEPARATOR, AND THE 15 BIT LOCATION ADDRESS (5 OCTAL DIGITS). THE ADDRESS IS IMMEDIATELY FOLLOWED BY "\ " TO SEPARATE THE CONTENTS FROM THE ADDRESS. FUTIL - OS/8 FILE UTILITY PROGRAM JAN. 17, 1973 PAGE 7 [N]"LINE-FEED" CLOSE THE CURRENT LOCATON, OPEN & TYPE OUT THE CONTENTS OF THE NEXT SEQUENTIAL LOCATION IN THE CURRENT 'OUTPUT' MODE. [N]! CLOSE THE CURRENT LOCATION, OPEN & TYPE OUT THE CONTENTS OF THE PREVIOUS SEQUENTIAL LOCATION IN THE CURRENT 'OUTPUT' MODE. [N]^ CLOSE CURRENT LOCATION, OPEN THE LOCATION THAT WOULD HAVE BEEN REFERENCED IF THE CONTENTS WERE A MEMORY REFERENCE INSTRUCTION, AND TYPE OUT 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 THE INDIRECT BIT OF THE INSTRUCTION IS A 1, THIS COMMAND WILL NOT DO THE INDIRECT!!! [N]_ 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. 12 BIT ARITHMETIC IS USED AND THE BLOCK PART IS IGNORED, SO THIS WILL WORK ONLY WITHIN THE CURRENT FIELD. [L]- OPEN THE LOCATION [L] LOCATIONS BACKWARD FROM THE CURRENT LOCATION AND TYPE OUT ITS CONTENTS IN THE CURRENT 'OUTPUT' MODE. SAME RESTRICTIONS AS WITH THE '+' COMMAND. THE "CURRENT 'OUTPUT' MODE" IS MENTIONED SEVERAL TIMES ABOVE. THE PROGRAM WILL TYPE OUT 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 OF THE WORD. THIS 'SYMBOLIC' TYPEOUT IS APPROXIMATELY THE WAY THAT YOU WOULD EXPECT THE INPUT TO THE ASSEMBLER TO BE IN ORDER TO GENERATE THE CONTENTS OF THE CURRENT LOCATION. IT IS ASSUMED, OF COURSE, THAT THESE CONTENTS ARE A PDP-8 INSTRUCTION. 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, AND FOR TELETYPE AND HIGH-SPEED PAPER-TAPE IOTS. SEE ALSO THE 'OPTION' AND 'SHOW' COMMANDS. FUTIL - OS/8 FILE UTILITY PROGRAM JAN. 17, 1973 PAGE 8 WORD-TYPE COMMANDS: ------------------- THESE COMMANDS ARE GROUPED BY FUNCTION, AS FOLLOWS: GROUP 1: FORMAT SET UP OUTPUT FORMAT FOR 'DUMP', 'LIST' & 'MODIFY'. DUMP TYPE OR LIST OUT THE CONTENTS OF ONE OR MORE BLOCKS. LIST TYPE OR LIST OUT THE CONTENTS OF ONE OR MORE LOCATIONS. MODIFY MODIFY ONE OR MORE LOCATIONS. GROUP 2: WORD WORD SEARCH STRING STRING SEARCH SMASK STRING SEARCH MASK GROUP 3: OPTION SET UP PROGRAM SWITCHES & VARIABLES SHOW SHOW SETTINGS OF PROGRAM SWITCHES & VARIABLES FILE LOOK UP FILE(S) ON DEVICE WRITE WRITE OUT CURRENT BUFFER REWIND MOVE DEVICE TO BLOCK 1 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 THE "BUILD" PROGRAM. 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: IN MANY CASES, TWO OR MORE WORDS WILL 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. FUTIL - OS/8 FILE UTILITY PROGRAM JAN. 17, 1973 PAGE 9 FORMAT ------ THE 'FORMAT' COMMAND IS USED TO SET UP THE OUTPUT FORMAT FOR THE "$" (SINGLE-CHARACTER) COMMAND DESCRIBED EARLIER AND THE DEFAULT FORMAT FOR THE 'DUMP', 'LIST' AND 'MODIFY' COMMANDS DESCRIBED BELOW. THIS COMMAND HAS THE FOLLOWING TWO FORMS: FORMAT [FORMAT] FOR PA F [FORMAT] F OS WHERE THE [FORMAT] IS ONE OF THE FOLLOWING: ASCII OUTPUT EACH WORD AS A SINGLE ASCII CHAR- A ACTER. PACKED OUTPUT EACH WORD AS TWO 6-BIT PACKED P ASCII CHARACTERS. 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. UNSIGNED OUTPUT EACH WORD AS AN UNSIGNED DECIMAL U NUMBER. SIGNED OUTPUT EACH WORD AS A SIGNED DECIMAL S NUMBER. OCTAL OUTPUT EACH WORD AS AN OCTAL NUMBER. O BCD OUTPUT EACH WORD AS 3 BCD DIGITS. B SYMBOLIC OUTPUT EACH WORD AS AN OCTAL NUMBER, FOLLOWED BY 2 SPACES AND ITS MNEMONIC REPRESENTATION, ASSUMING IT TO BE A PDP-8 INSTRUCTION. SEE THE PARAGRAPH FOLLOWING THE SINGLE-CHARACTER COMMAND DESCRIPTIONS (PAGE 7). THE FORMAT IS INITIALIZED TO PACKED ASCII ('PACKED'). 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: FUTIL - OS/8 FILE UTILITY PROGRAM JAN. 17, 1973 PAGE 10 [BLOCK].[ADDRESS]: E.G. "1271.17205: "--LOCATION 17205(8) RELATIVE TO BLOCK 1271(8). 2) THE NUMBER OF WORDS PER LINE IS SET UP AS FOLLOWS: A. THE THREE CHARACTER FORMATS OUTPUT 16 WORDS PER LINE WITH NO EXTRA CHARACTERS. B. THE FOUR NUMERIC FORMATS OUTPUT 8 WORDS PER LINE WITH 2 SPACES BETWEEN EACH NUMBER. C. THE 'SYMBOLIC' FORMAT OUTPUTS 1 WORD PER LINE. DUMP ---- THE 'DUMP' COMMAND IS USED TO OUTPUT ONE OR MORE WHOLE 256 WORD DEVICE BLOCKS IN THE CURRENT FORMAT. THIS COMMAND HAS THE FOLLOWING FORMS: 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 THE ONES GIVEN 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 [START BLOCK]-[END BLOCK] THE "," IS USED TO SEPARATE SINGLE BLOCKS OR GROUPS OF BLOCKS IF THERE IS MORE THAN ONE PER LINE. 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 'OPTION' COMMAND FOR SETTING THE LIST DEVICE AND THE MISCEL- LANEOUS INFORMATION SECTION FOR DEVICE USAGE INFORMATION. LIST ---- THE 'LIST' COMMAND IS USED TO OUTPUT THE CONTENTS OF ONE OR MORE WORDS ON THE DEVICE. THIS COMMAND HAS THE FOLLOWING FORMS: 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 FUTIL - OS/8 FILE UTILITY PROGRAM JAN. 17, 1973 PAGE 11 WHERE THE OPTIONAL [FORMAT] IS ONE OF THE ONES GIVEN 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] WHERE THE "[BLOCK]." PART IS OPTIONAL. IF THE BLOCK PART IS NOT SPECIFIED, THE LAST BLOCK NUMBER SPECIFIED TO THE PROGRAM WILL BE USED. AS WITH THE 'DUMP' COMMAND, THE OUTPUT FROM THE 'LIST' COMMAND IS SENT TO THE 'LDEV'. SEE THE PARAGRAPH ABOVE THIS COMMAND, THE 'OPTION' COMMAND AND THE MISCELLANEOUS INFORMA- TION SECTION FOR MORE INFORMATION. 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 [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 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 CORRES- PONDS TO THE CURRENT SETTING BY THE 'FORMAT' COMMAND. THE CORRESPONDING FORMATS ARE SHOWN BELOW. 'MODIFY' FORMAT 'FORMAT' SETTING AND DESCRIPTION ASCII ASCII--ONE CHARACTER OF INPUT IS STORED A IN EACH WORD TO BE MODIFIED. PACKED PACKED--TWO CHARACTERS OF INPUT ARE PACKED P AS 6-BIT CHARACTERS, PADDED WITH TRAILING 00'S. OS OS--THREE CHARACTERS OF INPUT ARE PACKED INTO TWO WORDS TO BE MODIFIED. WHEN USING THIS FORMAT, THE BEGINNING ADDRESS AND NUMBER OF WORDS TO BE MODIFIED MUST BOTH BE EVEN!!! FUTIL - OS/8 FILE UTILITY PROGRAM JAN. 17, 1973 PAGE 12 NUMERIC SIGNED & UNSIGNED DECIMAL, BCD, OCTAL AND N SYMBOLIC--THE INPUT IS A STRING OF NUMERIC ITEMS WHICH ARE STORED ONE PER 12 BIT WORD. 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 'FORMAT' COMMAND ABOVE. NOTE: 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 0. THE PROGRAM WILL NOT OUTPUT ANY MESSAGE IF EITHER OF THESE THINGS TAKE PLACE!! THIS DOES, HOWEVER, MAKE IT POSSIBLE TO ZERO ONE OR MORE BLOCKS ON A DEVICE BY SPECIFYING ALL THE WORDS TO BE ZEROED IN 'NUMERIC' FORMAT AND THEN RESPONDING TO THE PROMPT WITH A SINGLE "0" AND THE "RETURN". INPUT TO THE PROGRAM IS ALWAYS TERMINATED BY A CARRIAGE- 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"-"G", "CTRL"-"P", "CTRL"-"U" AND RUBOUT CHARACTERS CANNOT BE ENTERED USING THIS COMMAND EITHER. THE COMMAND CAN ALWAYS BE ABORTED BY "CTRL"-"P" IF YOU CHANGE YOUR MIND BEFORE THE "RETURN" KEY IS PRESSED. FUTIL - OS/8 FILE UTILITY PROGRAM JAN. 17, 1973 PAGE 13 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 'OPTION' COMMAND (THE DEFAULT) OR THE LIMITS SET UP BY THE "IN [L] TO [L]" CLAUSE 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 LIMIT SET BY THE 'OPTION' COMMAND. WHEN IN 'FILE' MODE, SEARCHING THROUGH NONEXISTENT LOCATIONS 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. 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 'OPTION' COMMAND), WILL MATCH THE SEARCH WORD (ALSO MASKED). THIS COMMAND HAS FOUR OPTIONS AND THEREFORE HAS THE FORMS: 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 WO M [N] WO M 40 WORD IN [L] TO [L] [N] WO IN 213.0 TO 213.177 2317 W I [L] T [L] W I 1.35 TO 100.177 (S) ... AND ANY COMBINATION 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 TYPED OUT AS AN ABSOLUTE BLOCK NUMBER AND ADDRESS RATHER THAN AS A RELATIVE LOCATION, AND "MEMREF" MEANS THAT ONLY WORDS WHOSE HIGH-ORDER OCTAL DIGIT IS 0 THRU 5 (I.E. THE 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 TYPEOUT 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). FUTIL - OS/8 FILE UTILITY PROGRAM JAN. 17, 1973 PAGE 14 STRING (SEARCH) --------------- THE 'STRING' SEARCH COMMAND IS USED TO SEARCH FOR A STRING OF NUMBERS (BIT PATTERNS) UNDER AN OPTIONAL STRING MASK. THIS COMMAND ALSO HAS THREE OPTIONS AND THEREFORE HAS THE FORMS: STRING [NUMERIC STRING] ST 4557,0,0 S [NUMERIC STRING] S 1111,2222,3333 STRING MASKED [NUMERIC STRING] ST MA 4577,0,1203 ST M [NUMERIC STRING] S M 5566,0 STRING ABSOLUTE [NUMERIC STRING] ST AB 'PI,'P@ S A [NUMERIC STRING] ST A "A,"B STRING IN [L] TO [L] [NUMERIC STRING] ST I [L] T [L] [NUMERIC STRING] S I 1.0 T 7.0 'AB,'SL,'DR ... AND ANY COMBINATION 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 FUTIL.SV BLKS XXXX-YYYY SIZE 0026 (0022) OP MODE FILE SMASK (-1),0,0 ST M 4547,0,0 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. FUTIL - OS/8 FILE UTILITY PROGRAM JAN. 17, 1973 PAGE 15 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 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. FUTIL - OS/8 FILE UTILITY PROGRAM JAN. 17, 1973 PAGE 16 OPTION ------ THE 'OPTION' 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: OPTION [OPTION(S)] OP OU SYM ERR LONG MODE FI O [OPTION(S)] O LO 100.0 UP 123.377 WHERE THE OPTIONS ARE AS FOLLOWS: OUTPUT OCTAL SET THE OUTPUT MODE FOR THE SINGLE- OUTPUT O CHARACTER COMMANDS. INITIALIZED TO O SYMBOLIC "OCTAL". O S ERROR SHORT SET THE MODE FOR ERROR MESSAGE E S TYPEOUT. THE 'SHOW' 'ERRORS' E LONG COMMAND WILL TYPE OUT ALL ERROR ERROR L MESSAGES AND CODES FOR USE IN THE "SHORT" MODE. INITIALIZED TO "LONG". OFFSET [L] SET THE OFFSET TO THE 12 LOW ORDER BITS OF [L]. 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. THE HANDLER IS FETCHED AT THIS TIME. INITIALIZED TO "SYS" (DEVICE 01). LDEV TTY SET UP THE DEVICE FOR 'DUMP', 'LIST' LDEV LPT & 'SHOW ERR' COMMANDS. INITIALIZED TO "TTY". 'LDEV LPT' WILL FETCH THE "LPT" HANDLER FOR YOUR SYSTEM. MODE NORMAL SET UP THE FILE ACCESS MODE. MODE N THESE HAVE BEEN DESCRIBED MODE FILE PREVIOUSLY. INITIALIZED TO "NORMAL". MODE F MO OFFSET MO O FUTIL - OS/8 FILE UTILITY PROGRAM JAN. 17, 1973 PAGE 17 MASK [N] SET THE 'WORD' SEARCH MASK TO M [N] THE 12 LOW ORDER BITS OF [N]. INITIALIZED TO 7777 (OCTAL). WHERE THE [DEVICE NAME] IS AN ASSIGNED OR PERMANENT OS/8 MASS STORAGE DEVICE NAME. 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 'OPTION' COMMAND, THE CURRENT FORMAT SET BY THE 'FORMAT' COMMAND AND OTHER INFORMATION. THE PROGRAM TYPES OUT EITHER WORDS OR NUMBERS OR WHATEVER TO BEST DESCRIBE THE CURRENT SETTINGS. AS WITH THE 'OPTION' 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 WHERE THE [OPTIONS] ARE AS FOLLOWS: BLOCK TYPE OUT IN OCTAL THE START BLOCK NUMBER B OF THE LAST FILE SPECIFIED BY THE 'FILE' COMMAND. CCB TYPE OUT 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 TYPED AS A 5-DIGIT OCTAL NUMBER, THE JOB STATUS WORD (JSW) IS TYPED IN OCTAL, AND THE CORE SEGMENTS ARE TYPED AS 5-DIGIT OCTAL ADDRESSES. ABSOLUTE TYPE OUT 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). FUTIL - OS/8 FILE UTILITY PROGRAM JAN. 17, 1973 PAGE 18 RELATIVE TYPE OUT THE RELATIVE LOCATION (WHAT YOU R SPECIFIED) OF THE LAST WORD ACCESSED ON THE DEVICE IN [L] FORMAT. ODT TYPE OUT THE RELATIVE LOCATION OF THE LAST WORD ACCESSED BY ONE OF THE SPECIAL-CHAR- ACTER COMMANDS IN [L] FORMAT. LOWER TYPE OUT THE SEARCH LOWER LIMIT IN [L] FORMAT. UPPER TYPE OUT THE SEARCH UPPER LIMIT IN [L] FORMAT. MASK TYPE OUT THE 'WORD' SEARCH MASK IN OCTAL. M SMASK TYPE OUT THE CURRENT CONTENTS OF THE 'STRING' SEARCH MASK AS A STRING OF OCTAL NUMBERS. OFFSET TYPE OUT IN OCTAL THE CURRENT VALUE OF THE OFFSET. MODE TYPE OUT THE NAME OF THE CURRENT SETTING OF THE FILE ACCESS MODE SWITCH (NORMAL, FILE OR OFFSET). DEVICE TYPE OUT THE NAME OF THE CURRENT OS/8 DEVICE AND ITS NUMBER. OUTPUT TYPE OUT THE NAME OF THE CURRENT SINGLE- O CHARACTER (ODT) COMMAND OUTPUT MODE (OCTAL OR SYMBOLIC). FORMAT TYPE OUT THE NAME OF THE CURRENT FORMAT F AS SET BY THE LAST 'FORMAT' COMMAND. ERRORS TYPE OUT A COMPLETE LIST OF ALL ERROR CODES E AND THEIR CORRESPONDING MESSAGES. NOTE: THIS LIST IS OUTPUT TO THE 'LDEV' (LIST DEVICE), AND SO WILL GO OUT ON THE "LPT" IF THAT IS HOW IT IS SET. FUTIL - OS/8 FILE UTILITY PROGRAM JAN. 17, 1973 PAGE 19 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 'FILE' MODE, 'SHOW' 'CCB', ETC. THIS COMMAND HAS THE FORM: FILE [FILE NAME STRING] FI FUTIL PIP.SV WHERE THE [FILE NAME STRING] IS A STRING OF ONE OR MORE OS/8 FILE NAMES, SEPARATED BY SPACES. THE PROGRAM ASSUMES AN EXTENSION OF "SV", SO A NULL EXTENSION, IF DESIRED, MUST BE SPECIFIED BY MAKING THE "." THE LAST CHARACTER OF THE FILE NAME. THE PROGRAM DOES A SEPARATE LOOKUP FOR EACH FILE NAME SPECIFIED AND OUTPUTS EITHER [FILE NAME] BLKS SSSS-EEEE SIZE OOOO (DDDD) MM/DD/YR OR [FILE NAME] BLKS SSSS-EEEE SIZE OOOO (DDDD) 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, AND MM/DD/YR IS THE FILE DATE. IF THE DIRECTORY DOES NOT CONTAIN THE EXTRA WORD REQUIRED FOR THE DATE, 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 LOCKED INTO CORE WHEN PROGRAM EXECUTION BEGINS. SINCE THE USR KEEPS TRACK OF THE CURRENT DEVICE ONCE THE FIRST 'FILE' COMMAND IS GIVEN, IT WILL HAVE THE WRONG DIRECTORY IN CORE 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) RESTART THE PROGRAM AT 00200. IT WILL READ IN A NEW COPY OF THE USR (WITH NO DIRECTORY SEGMENT). BOTH OF THESE METHODS SHOULD BE FOLLOWED BY AN 'OPTION' COMMAND TO RESET THE 'DEVICE' (AND THE REST OF THE SWITCHES IN THE PROGRAM). FUTIL - OS/8 FILE UTILITY PROGRAM JAN. 17, 1973 PAGE 20 THE LAST FILE NAME SPECIFIED THAT DID NOT HAVE A LOOKUP FAIL WILL BE THE FILE USED IN THE 'FILE' MODE, 'SHOW' 'CCB', ETC. THE PROGRAM IS INITIALIZED WITH NO KNOWN FILE, SO ATTEMPTING TO ACCESS ANY LOCATION IN FILE MODE 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 AND MUST BE TERMINATED BY THE "RETURN" KEY. REWIND ------ THE 'REWIND' COMMAND IS USED TO MOVE A TAPE BACK TO BLOCK 1. IT HAS THE FORM: REWIND AND ALSO MUST BE TERMINATED BY THE "RETURN" KEY. IT CAUSES A READ OF BLOCK 1 OF THE DEVICE AND RESETS THE DIRECTORY SEG- MENT KEY WORD IN THE USR. ANY SUBSEQUENT 'FILE' COMMAND WILL CAUSE THE DIRECTORY TO BE READ. FUTIL - OS/8 FILE UTILITY PROGRAM JAN. 17, 1973 PAGE 21 EVAL ---- THE 'EVAL' COMMAND IS USED TO EVALUATE A PARENTHESIZED EXPRESSION OF SIGNED DOUBLE-PRECISION INTEGERS. IT HAS THE FORM: EVAL [EXPRESSION] WHERE THE [EXPRESSION] FOLLOWS ALL 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 UNDER THE CONTROL OF THE "CTRL"-"D" AND "CTRL"-"K" SWITCHES), 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"). 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)" WHERE "OOOOOOOO" IS THE DOUBLE PRECISION RESULT IN OCTAL AND "SDDDDDDD" IS THE SIGNED-DOUBLE-PRECISION RESULT IN DECIMAL (THE SIGN IS EITHER "-" OR " "). FUTIL - OS/8 FILE UTILITY PROGRAM JAN. 17, 1973 PAGE 22 ADDITIONAL EXAMPLES: -------------------- THESE EXAMPLES ARE TO HELP PROVIDE AN OVERVIEW OF THE USE OF THE PROGRAM. 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 BLKS 0243-0351 SIZE 0107 (0071) 08/30/72 OP MASK 0 LO 234.0 UP 351.377 --SET UP MASK & LIMITS W UNE 0 --SEARCH THE FILE ? AT 08 FATAL READ ERROR --HERE IS THE PROBLEM SH ABS --FIND OUT WHERE IT IS ABS. LOC = 0271.00000 WR --ATTEMPT TO CLEAR PARITY 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 IN 272.0 TO 352.0 0 --CHECK THE REST OF THE FILE ^C --OK, NOW GO FIX THE SOURCE IF THE ERROR HAD BEEN OF SOME TYPE OTHER THAN A PARITY 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 WILL NOT BE CORRECT AND WILL HAVE TO BE CORRECTED WITH THE EDITOR. NOTE: 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 AN EXPLANATION. FUTIL - OS/8 FILE UTILITY PROGRAM JAN. 17, 1973 PAGE 23 2) AFTER USING BUILD TO CHANGE YOUR SYSTEM, FIND OUT THE DEVICE NUMBER FOR "DTA1": .R FUTIL OP DEV DTA1 --FETCH THE DEVICE HANDLER SHOW DE DEVICE = DTA1 (06) --NUMBER IS DECIMAL 3) BY ACCIDENT YOU ZERO A 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 OP DEV DTA1 --IT WAS HERE EV ^D5+14+11+10+16+13+8+5 --LENGTHS OF ALL PRECEDING FILES = 00000122 ( 0000082) EV ^D730-^K61-^D82-25 --REST OF TAPE ROOM = 00001076 ( 0000574) 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 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 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. FUTIL - OS/8 FILE UTILITY PROGRAM JAN. 17, 1973 PAGE 24 4) SEARCH FOR THE END OF EACH PAGE OF TEXT IN THE FILE "WRITE.UP". SINCE THE FILE IS AN OS/8 ASCII FILE, THE FORM-FEED CHARACTER (^L) MAY BE PACKED AS THE THIRD CHAR- ACTER IN SOME CASES. DO IT AS FOLLOWS: .R FUTIL FI WRITE.UP WRITE.UP BLKS 0301-0437 S^P --TYPEOUT STOPPED OP MA 377 OP LO 301.0 UP 437.377 --CHAR MASK & LIMITS SET W A "^L --SEARCH FOR FORM-FEED ....... TYPEOUT OCCURS HERE SMASK 7400,7400 --SET UP STRING MASK S M A ("^L*20),("^L*400) --SEARCH FOR 3RD CHAR F-F ....... MORE TYPEOUT HERE 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 "/9" SWITCH TO ABSLDR. FIX THE CCB (CORE-CONTROL- BLOCK) AS FOLLOWS: .ST --IT'S ALREADY IN CORE FI FUTIL FUTIL.SV BLKS 0341-^P --STOP OUTPUT 341.1/ 6203 --THE "CDF CIF" PART & 0341.00002\ 0200 -- THE ADDRESS 0341.00003\ 2000 2001 --CHANGE THE J.S.W. WR --WRITE THE NEW CCB SHOW CCB --CHECK IT THIS WAY CCB: SA = 00200, JSW = 2001 CORE^P --OK, OUTPUT STOPPED FUTIL - OS/8 FILE UTILITY PROGRAM JAN. 17, 1973 PAGE 25 MISCELLANEOUS INFORMATION: -------------------------- ASSEMBLING, LOADING & CREFING THE PROGRAM: ------------------------------------------ ASSEMBLE AND LOAD THE PROGRAM AS FOLLOWS: .R PAL8 *FUTIL,FUTIL [N]$ [N]: [N]"RETURN" [N]"LINE-FEED" [N]! [N]^ [N]_ [L]+ [L]- WORD-TYPE COMMANDS: (AND MODIFIERS, MANY OF WHICH ARE OPTIONAL) FORMAT [FORMAT] ASCII PACKED OS UNSIGNED SIGNED BCD OCTAL SYMBOLIC DUMP [FORMAT] [BLOCK STRING] (OPTIONAL [FORMAT]S ABOVE) LIST [FORMAT] [LOCATION STRING] (OPTIONAL [FORMAT]S ABOVE) MODIFY [FORMAT] [LOCATION STRING] (OPTIONAL [FORMAT]S BELOW) ASCII PACKED OS NUMERIC WORD [OPTION(S)] [N] UNEQUAL ABSOLUTE MEMREF IN [L] TO [L] STRING [OPTION(S)] [NUMBER STRING] MASKED ABSOLUTE IN [L] TO [L] SMASK [NUMBER STRING] E.G. 1,34,0,7700,0,(-1),377 OPTION [OPTION] [SETTING] OUTPUT OCTAL SYMBOLIC ERROR LONG SHORT OFFSET [L] LOWER [L] UPPER [L] DEVICE [DEVICE NAME] LDEV TTY LPT MODE NORMAL FILE OFFSET MASK [N] SHOW [OPTION(S)] BLOCK CCB ABSOLUTE RELATIVE ODT LOWER UPPER MASK SMASK OFFSET MODE DEVICE OUTPUT FORMAT ERRORS FILE [FILE NAMES(S)] WRITE REWIND 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 ^G RUBOUT