.COMMENT	[311,206]MTU.RNO
.COMMENT
.COMMENT	REVISIONS:
.COMMENT	26-JUL-77 (MK)	UPDATE FOR NEW RNO

.SPACING 1
.LEFT MARGIN 5
.RIGHT MARGIN 70
.NOFILL
.TITLE      ^^MAGTAPE UTILITY PROGRAM  (MTU)\\        16 ^SEPTEMBER 1976
.SKIP 3
^^CONTENTS\\
.SKIP 1
####^INTRODUCTION TO ^^MTU\\
##^I ^INITIATING ^^MTU\\
^^#II MTU C\\OMMAND ^STRINGS
^^III MTU S\\WITCHES
#^^IV C\\OMMAND AND ^SWITCH ^PROCESSING
^^##V MTU E\\RROR ^MESSAGES
#^^VI N\\OTES ON ^DOUBLE ^FILE ^MARK ^PROCESSING
.SKIP 3
^INTRODUCTION TO ^^MTU\\
.FILL
.PARAGRAPH
^THE ^MAGTAPE ^UTILITY ^PROGRAM (^^MTU\\) IS DESIGNED TO ENABLE THE
USER TO READ,
TRANSLATE, LIST AND COPY MAGTAPES OF VARIOUS FORMATS. ^TAPE
CHARACTERISTICS (E.G. DENSITY, PARITY, FORMAT) ARE SPECIFIED
VIA SWITCHES. ^IN A TYPICAL APPLICATION, ^^MTU\\ CAN READ A TAPE IN
ONE FORMAT, PERFORM THE NECESSARY TRANSLATIONS AND WRITE THE INFORMATION,
IN A DIFFERENT FORMAT, ON ANOTHER  TAPE.
^IN THE PROCESS, A LISTING OF THE INPUT TAPE CAN BE CREATED 
AND OUTPUT TO ANY DEVICE, WITH LISTING OPTIONS SPECIFIED BY
SWITCHES. ^IN ADDITION TO SEVERAL TAPE POSITIONING FUNCTIONS (E.G.
REWIND, SKIP RECORDS, SKIP FILES) A VERIFY OPTION IS INCLUDED
TO INSURE THAT A SUCCESSFUL COPY HAS BEEN OBTAINED.
.SKIP 3
.INDENT -3
^I.#^INITIATING ^^MTU\\
.PARAGRAPH
^BEFORE INITIATING ^^MTU\\, ALL TAPES SHOULD BE MOUNTED:
.SKIP 1
.TAB STOPS 12 58
	^^MOU MT\\N:/^^CHA=[ATCH,FOR]\\
.PARAGRAPH
^^MTU\\ IS INITIATED AS FOLLOWS:
.SKIP 1
	^^MCR>MTU\\<CR>
.BREAK
	^^MTU>\\COMMAND STRING<CR>
.BREAK
	OR
.BREAK
	^^MCR>MTU\\ COMMAND STRING<CR>
.PARAGRAPH
^TO EXIT FROM ^^MTU\\, TYPE CONTROL ^Z (_^^Z).

.PAGE
.SKIP 3
.INDENT -4
^^II.#MTU\\ ^COMMAND ^STRINGS
.PARAGRAPH
^COMMANDS TO ^^MTU\\ HAVE THE FOLLOWING FORMAT:
.SKIP 1
	(1) OUTTAPE/^^SW\\1, LIST FILE/^^SW\\2 = INTAPE/^^SW\\3
.BREAK
	OR
.BREAK
	(2) @ INDIRECT FILE
.SKIP 1
^FOR OUTTAPE AND INTAPE, ONLY THE DEVICE NAME IS GIVEN (E.G., 
^^MT\\1:). ^IF THE DEVICE SPECIFICATION FOR INTAPE OR OUTTAPE IS
OMITTED, THAT PORTION OF THE COMMAND STRING IS IGNORED.
.BREAK
^FOR EXAMPLE:
.SKIP 1
	/^^ST\\
.BREAK	OR
.BREAK
	/^^RW = /ST\\
.SKIP 1
DO NOT CAUSE ANY ACTION TO BE TAKEN.
.SKIP 1
^IF ONLY THE OUTTAPE IS SPECIFIED
.SKIP 1
	OUTTAPE/^^SW\\1
.SKIP 1
THE EFFECT IS EITHER TO PERFORM THE INDICATED OPERATION OR TO
SET UP THE SPECIFIED TAPE FORMAT AS A DEFAULT FOR
THAT TAPE.
.BREAK
.SKIP 1
	^^MT0:/RW\\########REWINDS ^MAGTAPE ^UNIT 0.
.SKIP 1
	^^MT1:/55/EP/ST\\##SETS THE DENSITY AND PARITY DEFAULTS ON
.NOFILL
	     ^^MT1\\ TO 556 ^^BPI\\ AND EVEN PARITY. ^IT ALSO PRINTS
	     THE NEW DEFAULT STATUS ON THE USER TELETYPE.
.SKIP 1
.FILL
^IF BOTH INTAPE AND OUTTAPE ARE GIVEN, FORMAT SWITCHES
CHANGE THE FORMAT ONLY FOR THE DURATION OF THE COPY;
THE FORMAT THEN REVERTS TO THE PREVIOUS DEFAULTS.
.SKIP 1
^IF INTAPE IS SPECIFIED, EITHER OUTTAPE OR LIST FILE, OR BOTH, MAY BE
OMITTED. ^IF BOTH ARE OMITTED
.SKIP 1
.NOFILL
	=INTAPE/^^SW3\\
.SKIP 1
.FILL
THEN INTAPE IS READ, BUT IS NEITHER COPIED NOR LISTED. ^THIS MODE IS
USEFUL FOR CHECKING A TAPE FOR READABILITY.

.PAGE
.SKIP 3
.INDENT -5
^^III.#MTU S\\WITCHES
.PARAGRAPH
^^MTU\\ SWITCH SPECIFICATIONS CONSIST OF A SLASH (/)
FOLLOWED BY TWO LETTERS. ^CERTAIN SWITCHES ALSO HAVE AN OPTIONAL
DECIMAL VALUE WHICH IS SEPARATED FROM THE SWITCH BY A COLON (:).
.PARAGRAPH
^A DESCRIPTION OF THE AVAILABLE SWITCHES AND THEIR
FUNCTIONS FOLLOWS.
.SKIP 1
^SWITCHES FOR OUTTAPE AND/OR INTAPE:
.NOFILL
.SKIP 1
^^SWITCH	        FUNCTION	  USE
.SKIP 1
/KS	T\\APE IS IN ^K^S90 FORMAT	^^SW1 _& SW3
/BE	T\\APE IS IN ^BERKELEY FORMAT	^^SW1 _& SW3
/IM	T\\APE IS IN ^IMAGE FORMAT (DEFAULT)	^^SW1 _& SW3
/20	T\\APE IS 200 ^^BPI	SW1 _& SW3
/55	T\\APE IS 556 ^^BPI	SW1 _& SW3
	\\  (DEFAULT IF /^K^S OR /^B^E SPECIFIED)
/80	^TAPE IS 800 ^^BPI	SW1 _& SW3
/CD	T\\APE IS IN CORE DUMP MODE	^^SW1 _& SW3
	\\  (DEFAULT IF /^I^M SPECIFIED OR IMPLIED)
/^^EP	T\\APE IS EVEN PARITY	^^SW1 _& SW3
/-EP	T\\APE IS ODD PARITY (DEFAULT)	^^SW1 _& SW3
/RW	R\\EWIND TAPE BEFORE COPY	^^SW1 _& SW3
/SF:N	S\\KIP ^N FILES BEFORE COPY	^^SW1 _& SW3
/SR:N	S\\KIP ^N RECORDS BEFORE COPY	^^SW1 _& SW3
	  (N\\ NEGATIVE MEANS BACKWARDS FOR /^^SF _& /SR)
/WF:N	W\\RITE ^N FILE MARKS ON OUTPUT TAPE	^S^W1 ONLY
	  AFTER COPY (DEFAULT=1)
/^^ST	P\\RINT CURRENT TAPE FORMAT DEFAULTS	^S^W1 ONLY
/^^RE:N	R\\EAD ^N RECORDS OR UNTIL THE NEXT FILE MARK	^S^W3 ONLY
/^^FI:N	R\\EAD ^N FILES OR UNTIL DOUBLE FILE MARK	^S^W3 ONLY
/^^VE	C\\OMPARE INPUT _& OUTPUT TAPES AND	^^SW1 _& SW3\\
	  NOTE ANY DISCREPANCIES
.PARAGRAPH
.FILL
^IF CONTRADICTORY SWITCHES ARE SPECIFIED FOR THE TAPE
FORMAT, THE LATER SWITCHES IN THE ABOVE LIST WILL 
OVERRIDE THE EARLIER ONES.
.NOFILL
.SKIP 1
^SWITCHES THAT SPECIFY THE FORMAT OF THE LISTING ARE:
.SKIP 1
^^/^^LG	D\\UMP LOGICAL LENGTH (DEFAULT--IMPLIED WITH ALL SWITCHES)
/^^OW	D\\UMP OCTAL WORDS
/^^OB	D\\UMP OCTAL BYTES
/^^DW	D\\UMP DECIMAL WORDS (SIGNED)
/^^DB	D\\UMP DECIMAL BYTES (MAGNITUDE)
/^^AS	D\\UMP ^^ASCII\\ BYTES
/^^RA	D\\UMP ^^RAD\\50 WORDS
.FILL
.PARAGRAPH
^MULTIPLE LISTING SWITCHES MAY BE SPECIFIED. ^IN THIS CASE, THE TAPE IS
LISTED IN ALL FORMATS REQUESTED, WITH THE FORMATS INTERSPERSED 
LINE-BY-LINE.

.PAGE
.SKIP 3
.INDENT -4
^^IV.#C\\OMMAND AND ^SWITCH ^PROCESSING
.PARAGRAPH
^^MTU\\ USES ROUTINES PROVIDED BY ^^RSX-11D\\ TO FETCH AND PARSE 
COMMANDS AND THEREFORE THE SYNTAX AND USER PROCEDURES ARE SIMILAR
TO THOSE OF OTHER UTILITIES.
.PARAGRAPH
^^MTU\\ PERFORMS TAPE OPERATIONS (IF REQUESTED) IN THE FOLLOWING ORDER:
.SKIP 1
.NOFILL
(1)##^REWIND OUTPUT.
(2)##^SKIP FILES ON OUTPUT.
(3)##^SKIP RECORDS ON OUTPUT.
(4)##^REWIND INPUT.
(5)##^SKIP FILES ON INPUT.
(6)##^SKIP RECORDS ON INPUT.
(7)##^COPY INPUT TO OUTPUT OR VERIFY OUTPUT AGAINST INPUT;
#####PRODUCE LISTING IF REQUESTED.
(8)##^WRITE FILE MARKS ON OUTPUT OR VERIFY THE PRESENCE OF
#####FILE MARKS ON OUTPUT.
.FILL
.PARAGRAPH
^IT IS IMPORTANT TO NOTE THAT THE FIELDS (OUTTAPE,
LIST FILE AND INTAPE) ARE PROCESSED SEQUENTIALLY AND THAT
EACH IS PROCESSED COMPLETELY BEFORE THE NEXT ONE IS CHECKED FOR
VALID SWITCHES, DEVICES, ETC. ^THEREFORE IT IS POSSIBLE
FOR PART OF A DESIRED OPERATION TO BE PERFORMED BEFORE
AN ERROR IS DISCOVERED IN THE COMMAND.
^FOR EXAMPLE, THE COMMAND:
.SKIP 1
	^^MT0:/SF:5/RW=MT1:/XX\\
.BREAK
WOULD CAUSE THE FOLLOWING TO OCCUR:
.SKIP 1
(1) ^^MT0:\\ WOULD REWIND,
.BREAK
(2) ^FIVE FILES WOULD BE SKIPPED ON ^^MT0\\:,
.BREAK
(3) ^SINCE /^X^X IS NOT A VALID SWITCH, ^^SWITCH ERROR\\ WOULD
.BREAK
####BE PRINTED ON THE USER TERMINAL,
.BREAK
(4) ^^MTU\\ WOULD SOLICIT ANOTHER COMMAND.
.FILL
.PARAGRAPH
^WHEN THE VERIFY (/^V^E) SWITCH IS USED, ALL OTHER SWITCHES WORK
AS FOR COPYING EXCEPT THAT ^^/WF:N\\ CHECKS FOR THE
PRESENCE OF ^N CONSECUTIVE FILE MARKS RATHER THAN WRITING THEM.
.PARAGRAPH
^IF NEITHER ^^/FI:N\\ OR ^^/RE:N\\ IS GIVEN AFTER INTAPE, ^^MTU\\
WILL COPY OR VERIFY UNTIL A DOUBLE END OF FILE IS REACHED.
.PARAGRAPH
^WHEN CREATING A LISTING ON A FILE STRUCTURED DEVICE,
IF THE FILENAME IS NOT SPECIFIED, THE DEFAULT
FILENAME ^^MTULIST.LST\\ IS USED.

.PAGE
.SKIP 3
.INDENT -3
^^V.#E\\RROR ^MESSAGES
.PARAGRAPH
^ERRORS RETURNED BY ^^MTU\\ CAN BE CLASSED IN FOUR CATAGORIES.
.SKIP 2
(1) ^COMMAND ^ERRORS. ^COMMAND FETCH ERRORS, SYNTAX 
ERRORS, AND SWITCH ERRORS ARE REPORTED BY THE FOLLOWING
MESSAGES:
.SKIP 1
.NOFILL
.SPACING 2
^^COMMAND LINE I/O ERROR
OPEN ERROR ON INDIRECT FILE
INDIRECT COMMAND SYNTAX ERROR
INDIRECT FILE DEPTH EXCEEDED
SYNTAX ERROR
SWITCH ERROR\\
.SPACING 1
.PARAGRAPH
.FILL
^IF A COMMAND ERROR OTHER THAN THOSE ABOVE IS DETECTED,
^^COMMAND ERROR\\ IS PRINTED.
.PARAGRAPH
^IF A COMMAND REQUESTING A LISTING FILE WITHOUT
SPECIFYING INTAPE IS FOUND, ^^INPUT SPECS\\? IS PRINTED.
.SKIP 1
^FOR EXAMPLE:
.SKIP 1
	^^MT0:,LP:/OW<CR>
.BREAK
	INPUT SPECS?\\
.PARAGRAPH
^IF A MAGTAPE OPERATION IS SPECIFIED ON A NON-EXISTENT
UNIT OR IF A UNIT NUMBER GREATER THAN SEVEN IS GIVEN,
^^DEVICE NOT IN SYSTEM\\ IS PRINTED.
.SKIP 2
(2) ^MAGTAPE ^ERRORS. ^WHEN AN ERROR OCCURS WHILE PERFORMING
A MAGTAPE OPERATION, THE MAGTAPE HANDLER RETURNS AN ERROR STATUS 
CODE. ^^MTU\\ ASSOCIATES THE FOLLOWING MESSAGES WITH THESE CODES.
.SKIP 1
.NOFILL
.SPACING 2
^^FUNCTION VALIDATION ERROR
OPERATION ABORTED*
TAPE FORMAT ERROR
ODD ADDRESS ERROR
DEVICE ALREADY ATTACHED*
RECORD LENGTH ERROR
DEVICE NOT ATTACHED
DEVICE OFF-LINE*
FILE MARK--RECORDS READ/SKIPPED=N
DOUBLE FILE MARK--FILES READ/SKIPPED=N
EOT
FATAL HARDWARE ERROR*
TAPE MUST BE MOUNTED [ATCH,FOR]*
INVALID FUNCTION CODE
SEND/REQUEST FAIL
PARITY ERROR
WRITE LOCK*\\
.SPACING 1
.SKIP 1
* ^DENOTES FATAL ERROR
.FILL
.BREAK
.SKIP 1
^IF AN ERROR CODE CANNOT BE MATCHED WITH ONE
OF THE ABOVE MESSAGES, ^^TAPE ERROR\\ IS PRINTED.
.PARAGRAPH
^FOLLOWING A MAGTAPE ERROR MESSAGE, THE MESSAGE
.SKIP 1
	^^ON INPUT\\ (OR ^^OUTPUT) TAPE-FILE N RECORD N\\
.SKIP 1
.BREAK
IS PRINTED TO INFORM THE USER WHICH TAPE WAS INVOLVED.
^IN ADDITION, ^^*FATAL\\* IS PRINTED IF THE ERROR IS
CLASSED AS FATAL. ^FOLLOWING A FATAL ERROR,
ALL PENDING ^I/^O IS ABANDONED AND ^^MTU\\ SOLICITS
ANOTHER COMMAND LINE. ^IF THE ERROR IS NOT FATAL,
HOWEVER, ^^MTU\\ CONTINUES EXECUTION.
.SKIP 2
(3) ^VERIFY ^ERRORS. ^ERRORS CONNECTED WITH THE /^^VE\\ SWITCH ARE
.SKIP 1
^^INSUFFICIENT BUFFER FOR VERIFY\\
.BREAK
^THE VERIFY BUFFER IS ONLY HALF THE SIZE OF THE READ/COPY
BUFFER AND THEREFORE IT MAY BE POSSIBLE TO COPY FILES THAT CANNOT 
BE VERIFIED.
.SKIP 1
^^RECORD LENGTH MISMATCH\\
.BREAK
^RECORDS BEING COMPARED HAVE DIFFERENT LENGTHS. ^THE VERIFY
OPERATION IS ABORTED.
.SKIP 1
^^EXPECTED FILE MARK(S) NOT FOUND\\
.BREAK
^WHEN /^V^E IS USED IN CONJUNCTION WITH /^^WF:N, MTU\\
CHECKS FOR THE EXISTENCE OF ^N FILEMARKS. ^IF ALL ARE NOT FOUND,
THIS MESSAGE IS PRINTED.
.SKIP 1
^^VERIFY ERROR - FILE N, RECORD N
.BREAK
	MISMATCH ON N WORD(S)\\
.BREAK
^TWO RECORDS OF THE SAME LENGTH HAD ^N WORDS DIFFERENT.
.SKIP 2
(4) ^LISTING ^ERRORS. ^ERRORS ASSOCIATED WITH THE LISTING FILE ARE
REPORTED AS FOLLOWS:
.SKIP 1
^^OPEN ERROR ON LIST FILE - ERR CODE = \\-NN.
.BREAK
^THE LISTING FILE COULD NOT BE OPENED SUCCESSFULLY.
^THE CODE MAY BE LOOKED UP IN THE ^EXECUTIVE ^REFERENCE ^MANUAL,
^APPENDIX ^C.
.SKIP 1
^^OUTPUT ERROR ON LIST FILE - ERR CODE = \\-NN.
.BREAK
^AN ERROR OCCURRED WHILE WRITING TO THE LIST FILE.
^THIS IS OFTEN CAUSED BY A DEVICE BECOMING FULL (NN=24).
.SKIP 1
^IN EITHER OF THESE CASES, THE OPERATION IN PROGRESS IS ABANDONED,
THE LISTING FILE IS CLOSED, AND ^^MTU\\ SOLICITS ANOTHER COMMAND LINE.

.PAGE
.SKIP 3
.INDENT -4
^^VI.#N\\OTES ON ^DOUBLE ^FILE ^MARK ^PROCESSING
.PARAGRAPH
.FILL
^WHEN ^^MTU\\ ENCOUNTERS A DOUBLE FILE MARK WHILE EITHER READING TAPE
OR SKIPPING FORWARD, IT OUTPUTS A MESSAGE TO THE TERMINAL AND TERMINATES
THE CURRENT OPERATION. ^THE TAPE IS LEFT POSITIONED BETWEEN THE TWO FILE
MARKS.
.PARAGRAPH
^IF A COPY WAS IN PROGRESS, BOTH FILE MARKS ARE WRITTEN ON THE OUTPUT TAPE,
AND THE OUTPUT TAPE IS POSITIONED BETWEEN THEM.
.PARAGRAPH
^SINCE A DOUBLE FILE MARK NORMALLY DENOTES THE END OF DATA ON A TAPE, THESE
ACTIONS ARE USUALLY APPROPRIATE. ^IF SEVERAL INPUT TAPES ARE TO BE MERGED
ONTO ONE OUTPUT, IT IS NOT NECESSARY TO REPOSITION THE OUTPUT BETWEEN
COPIES. ^IT IS RECOMMENDED THAT AFTER THE FINAL COPY, SEVERAL EXTRA
FILE MARKS BE WRITTEN ON THE OUTPUT (BY AN ^^MT1:/WF:5\\, FOR EXAMPLE).
.PARAGRAPH
^OCCASIONALLY, A TAPE IS ENCOUNTERED THAT CONTAINS DATA FOLLOWING A DOUBLE
FILE MARK. ^TO GET TO THIS DATA, IT IS NECESSARY TO GET PAST THE DOUBLE
FILE MARK. ^HOWEVER, WHEN A DOUBLE FILE MARK IS ENCOUNTERED DURING A 
FORWARD SKIP, A FLAG GETS SET IN THE MAGTAPE HANDLER THAT MAKES IT
IMPOSSIBLE TO SKIP FORWARD ANY FURTHER.
.PARAGRAPH
^FOR THIS REASON, THE WAY TO GET PAST A DOUBLE FILE MARK IS TO READ
(NOT SKIP) ONE FILE. ^THIS SPACES THE TAPE OVER THE SECOND FILE MARK AND
RESETS THE FLAG IN THE HANDLER, MAKING IS POSSIBLE TO SKIP FORWARD
FURTHER.
.PARAGRAPH
^THE SAME TECHNIQUE IS USED WHEN THERE IS A FILE MARK AT THE
BEGINNING-OF-TAPE, SINCE THIS LOOKS LIKE A DOUBLE FILE MARK TO THE HANDLER.
.SKIP 4
.NOFILL
^AUTHOR:##^MARSHALL ^LONG 
^REVISED BY:##^MARTIN ^KELLOGG
.PAGE