.PAGESIZE 60,70
.LM 7
.RM 70
.PAGE
.LC
.FL CAPITALIZE
.PAGE
.SKIP 6
.TITLE <MTEXCH ^VERSION 1.01
.CENTER; <MTEXCH
.SKIP
.CENTER; ^VERSION 1.01
.SKIP
.CENTER;  7 ^OCTOBER 1980
.SKIP 3
^INTRODUCTION:
.P  
<MTEXCH IS A <VAX UTILITY FOR COPYING FILES TO AND FROM MAGNETIC TAPE.
^IT IS USED FOR PROCESSING TAPES WHICH ARE NOT IN THE STANDARD <VAX
TAPE FORMAT.  <MTEXCH CAN HANDLE VARIOUS RECORD AND BLOCK FORMATS COMMONLY
FOUND ON TAPES WRITTEN ON NON-<DEC SYSTEMS. ^PARAMETERS CAN BE SPECIFIED
TO CONTROL RECORD LENGTH, RECORD FORMAT, BLOCK FORMAT, CHARACTER SET, 
CARRIAGE CONTROL, AND OTHER FILE ATTRIBUTES.  ^COPYING IS ALWAYS ON A 
RECORD BY RECORD BASIS.  ^THAT IS, THERE WILL ALWAYS BE EXACTLY ONE
OUTPUT RECORD FOR EACH INPUT RECORD.
.SKIP 3
^USING <MTEXCH:
.P
^BEFORE USING THE <MTEXCH PROGRAM, THE TAPE TO BE PROCESSED MUST BE 
MOUNTED USING A SEQUENCE OF COMMANDS SUCH AS:
.SKIP
.I 5
^^$ALLOCATE MTA\\N:  !^ALLOCATE A TAPE DRIVE
.I 5
^^$MOUNT/FOREIGN/BLOCKS=\\NNNN  ^^MTA\\N: !^MOUNT THE TAPE
.SKIP
^NOTE THAT THE TAPE IS PROCESSED AS "FOREIGN".  ^THIS MEANS THAT ALL LABEL
INFORMATION ON THE TAPE IS TREATED AS DATA.  ^ALSO NOTE THAT THE BLOCKSIZE
(IF DIFFERENT FROM THE DEFAULT OF 2048 BYTES) MUST BE SPECIFIED WHEN THE
TAPE IS MOUNTED.
<MTEXCH CAN THEN BE RUN WITH THE COMMAND:
.SKIP
.I 5
^^$RUN MTEXCH\\
.SKIP
^THE PROGRAM WILL PROMPT WITH THE "*" CHARACTER.  ^THE USER CAN THEN ENTER
<MTEXCH COMMAND STRINGS OF THE FORM:
.SKIP
.I 5
OUTFILE=INFILE1,INFILE2,....
.SKIP
<MTEXCH WILL PROCESS EACH COMMAND STRING AND THEN PROMPT FOR THE NEXT STRING.
^TYPING A CONTROL-^Z WILL TERMINATE <MTEXCH.
.P
^OUTFILE IS ANY VALID <VAX FILE SPECIFICATION THAT DOES NOT INCLUDE A WILDCARD.
^THIS PARAMETER SPECIFIES THE NAME OF THE FILE(S) TO RECEIVE THE DATA COPIED
FROM THE INPUT FILE(S).  ^INFILE1,... ARE THE FILE SPECIFICATIONS OF THE 
FILES TO BE READ BY <MTEXCH.  ^THE SPECIFICATIONS MAY BE ANY VALID <VAX 
FILE SPECS.  ^WILDCARDS ARE PERMITTED.  ^EXACTLY ONE OUTPUT FILE IS CREATED
FOR EACH INPUT FILE SPECIFIED.  ^IF THE OUTPUT FILE IS TAPE (^^MTA\\N:)
THE INPUT FILES WILL BE COPIED SEQUENTIALLY TO THE TAPE.  ^IF THE OUTPUT FILE
IS ON DISK, EACH INPUT FILE WILL CREATE A HIGHER VERSION OF THE SPECIFIED
OUTPUT FILE.  ^IF THE INPUT FILE IS TAPE AND SPECIFIES A WILDCARD (^^MTA\\N:*), ALL OF
THE FILES FROM THE CURRENT TAPE POSITION TO THE FIRST DOUBLE TAPE-MARK
WILL BE COPIED TO DISK.  ^NOTE THAT ONE FILE MUST ALWAYS BE ON DISK, AND
ONE MUST ALWAYS BE ON TAPE.
.P
^EACH FILE SPECIFICATION CAN OPTIONALLY BE FOLLOWED BY ONE OR MORE SWITCHES
WHICH SPECIFY THE ATTRIBUTES OF THE FILE. ^ALL SWITCHES MAY BE ABBREVIATED TO THEIR UNIQUE STEM. ^ALL OF THE SWITCHES ARE ACCEPTED
FOR ANY FILE.
^HOWEVER, SOME OF THE ATTRIBUTES ARE ONLY APPLICABLE TO 
<VAX DISK FILES.  ^ALSO, RECORD AND BLOCK FORMAT INFORMATION IS IGNORED FOR
FILES READ FROM DISK, AS THIS INFORMATION IS OBTAINED FROM THE FILE'S
ATTRIBUTES.  ^IF CONFLICTING SWITCHES ARE SPECIFIED FOR A FILE, THE LAST ONE 
ENCOUNTERED IS USED.  ^THE FOLLOWING SWITCHES ARE RECOGNIZED:
.SKIP
.LM 26
.INDENT -14
</ASCII#####-#^THE TAPE FILE IS OR SHOULD BE IN <ASCII (DEFAULT)
.SKIP
.INDENT -14
</EBCDIC####-#^THE TAPE FILE IS OR SHOULD BE IN <EBCDIC
.SKIP
.INDENT -14
^^/BLOCKSZ:\\N#-#^N IS THE NUMBER OF BYTES IN A TAPE BLOCK.  ^THIS PARAMETER
HAS NO REAL EFFECT, SINCE BLOCK SIZE IS SET ON THE <MOUNT COMMAND. ^A WARNING
IS ISSUED IF THE VALUE OF THIS PARAMETER CONFLICTS WITH THE ACTUAL TAPE BLOCKSIZE.
.SKIP
.INDENT -14
^^/RECLEN:\\N##-#^N IS THE NUMBER OF BYTES IN A RECORD.  ^FOR VARIABLE
LENGTH RECORDS, IT IS THE MAXIMUM.  ^THIS SWITCH IGNORED FOR DISK INPUT FILES.
^THE DEFAULT FOR TAPES IS 80.
.SKIP
.INDENT -14
</FIXED#####-#^RECORDS ARE FIXED LENGTH (DEFAULT FOR TAPE)
.SKIP
.INDENT -14
</VARIABLE##-#^RECORDS ARE VARIABLE LENGTH PREFIXED WITH A 2 BYTE
BINARY LENGTH (DEFAULT FOR DISK)
.SKIP
.INDENT -14
</FB########-#^BLOCKS ARE FIXED LENGTH WITH A FIXED NUMBER OF RECORDS PER BLOCK
(DEFAULT FOR TAPE)
.SKIP
.INDENT -14
</CR########-#^FOR A DISK FILE, SET  THE <CR CARRIAGE CONTROL ATTRIBUTE. (DEFAULT)
.SKIP
.INDENT -14
</FORTRAN###-#^FOR A DISK FILE, SET THE <FTN CARRIAGE CONTROL ATTRIBUTE.
.SKIP
.INDENT -14
</REWIND####-#^REWIND THE SPECIFIED TAPE.
.SKIP
.INDENT -14
</SKIPF:[-]\N-#^SKIP THE SPECIFIED TAPE FORWARD [BACKWARD] N FILES.
.SKIP 3
.LM 7
.NOTE 
^AT THIS TIME, THE RECORD AND BLOCK FORMATTING CAPABILITIES ARE NOT
FULLY IMPLEMENTED.  <MTEXCH CAN ONLY PROCESS </FIXED/FB FORMAT TAPES AND
/<VARIABLE DISK FILES.
.END NOTE
.PAGE
^SAMPLE ^COMMANDS:
.SKIP
.I 5
^^MTA1:/FIXED/FB=TEST1.DAT
.SKIP
.I 5
MT:/BLOCK:800/RECL:160=DRA1:[XYZ]XYZ.DAT
.SKIP
.I 5
PRINTFILE./FORTRA/VARIA=MT:/BLOCK:1320/RECL:132/EBCDIC
.SKIP
.I 5
[MASTER]CARDFILE/CR/FIXED=MT:*/RECL:80/ASCII
.SKIP
.I 5
MTA0:/REWI
.SKIP
.I 5
MT:/SKIPF:-2\\
.SKIP 3
^ERROR ^MESSAGES:
.SKIP
^^%MTEXCH-E-WCINOUT,\\ ^WILD CHARACTER ILLEGAL IN OUTPUT SPEC.
.BR
.LM 12
^A WILDCARD CHARACTER CAN ONLY APPEAR IN THE INPUT FILE SPECS, NEVER
IN THE OUTPUT SPEC.
.SKIP
.LM 7
^^%MTEXCH-E-BOTHREC,\\ ^BOTH INPUT AND OUTPUT FILES ARE DISK.
.BR
.LM 12
^ONLY ONE OF THE FILES CAN BE DISK.  ^IF THE INPUT FILES ARE DISK,
THE OUTPUT FILES MUST BE TAPE.
.SKIP
.LM 7
^^%MTEXCH-E-BOTHBLK,\\ ^BOTH INPUT AND OUTPUT FILES ARE TAPE.
.BR
.LM 12
^ONLY ONE OF THE FILES CAN BE TAPE.  ^IF THE INPUT FILES ARE TAPE, 
THE OUTPUT FILE MUST BE DISK.
.SKIP
.LM 7
^^%MTEXCH-F-IOERR, I/O\\ ERROR FOR FILE XXXXXXXXXXX.
.BR
.LM 12
^AN <RMS FUNCTION RETURNED AN UNEXPECTED ERROR CODE.  ^THIS MESSAGE IS
FOLLOWED WITH ANOTHER MESSAGE DESCRIBING THE ERROR.
.SKIP
.LM 7
^^%MTEXCH-E-UNKSW,\\ ^UNKNOWN SWITCH XXXXXXXXX.
.BR
.LM 12
^THE INDICATED SWITCH IS NOT RECOGNIZED AS VALID BY <MTEXCH.
.SKIP
.LM 7
^^%MTEXCH-E-AMBIG,\\ ^SWITCH ABBREVIATION XXXXXX IS AMBIGUOUS.
.BR
.LM 12
^THE INDICATED SWITCH ABBREVIATION IS TOO SHORT TO UNIQUELY IDENTIFY
ONE OF A GROUP OF SWITCHES WITH SIMILAR NAMES.
.SKIP
.LM 7
^^%MTEXCH-E-NOVAL, \\^VALUE REQUIRED FOR SWITCH XXXXXXX.
.BR
.LM 12
^THE INDICATED SWITCH MUST BE FOLLOWED BY A ":" AND A NUMERIC VALUE.
.SKIP
.LM 7
^^%MTEXCH-E-BADVAL\\, ^ILLEGAL VALUE XXXXXX
.BR
.LM 12
^THE INDICATED ITEM FOLLOWING A ":" WAS NOT A LEGAL VALUE FOR THE SWITCH
IT FOLLOWED.
.SKIP
.LM 7
^^%MTEXCH-W-TRU\\, ^INPUT FILE RECORD TRUNCATED.
.BR
.LM 12
^A RECORD ON THE INPUT FILE WAS LONGER THAN THE RECORD LENGTH SPECIFIED
FOR THE FILE.  ^THE RECORD IS TRUNCATED TO THE LENGTH THAT WAS SPECIFIED.
.SKIP
.LM 7
^^%MTEXCH-W-RECBLK, \\^RECORDS DO NOT EXACTLY FILL "<FB" TYPE BLOCK.
.BR
.LM 12
^A "<FB" TYPE BLOCK MUST BE EXACTLY FILLED BY AN INTEGRAL NUMBER OF RECORDS.
^THE LAST RECORD, WHICH WOULD EXCEED THE BLOCK LENGTH, IS TRUNCATED.
.SKIP
.LM 7
^^%MTEXCH-W-PUTTRU, \\^OUTPUT FILE RECORD TRUNCATED. ^LENGTH=NNN BYTES.
.BR
.LM 12
^A RECORD WAS OBTAINED FROM THE INPUT FILE WHICH WAS LONGER THAN THE
SPECIFIED LENGTH FOR THE OUTPUT FILE.  ^THE RECORD WAS TRUNCATED.  ^THE
ORIGINAL LENGTH IS LISTED.
.SKIP 
.LM 7
^^%MTEXCH-W-RECSHR, \\^SHORT RECORD ENCOUNTERED, ^LENGTH=NNN BYTES.
.BR
.LM 12
^WHEN READING A FILE OF FIXED LENGTH RECORDS, A RECORD WAS ENCOUNTERED
WHICH WAS NOT OF THE CORRECT LENGTH.  ^THIS COULD BE THE LAST RECORD
IN A BLOCK IF THE TAPE IS BEING READ WITH AN INCORRECT BLOCKSIZE.
.SKIP
.LM 7
^^%MTEXCH-W-BLKSZ, BLOCKSZ\\ VALUE DOESN'T MATCH VOLUME.
.BR
.LM 12
^THE SPECIFIED VALUE OF THE <BLOCKSZ SWITCH DOES NOT MATCH THE SIZE
DEFINED WHEN THE VOLUME WAS MOUNTED.
.LM 7
.SKIP
^^%MTEXCH-E-BASFSO,\\ ^BAD OR MISSING FILESPEC FOR OUTPUT.
.BR
.LM 12
^THE <MTEXCH COMMAND DOES NOT BEGIN WITH SOMETHING THAT IS 
RECOGNIZABLE AS AN OUTPUT FILE SPEC.
.LM 7
.SKIP
^^%MTEXCH-E-CHAN,\\ ^COULDN'T POSITION TAPE. ^CHANNEL ASSIGNMENT FAILED.
.BR
.LM 12
<MTEXCH CANNOT ACCESS THE SPECIFIED TAPE DRIVE TO ASSIGN A CHANNEL FOR <I/O.
.LM 7
.SKIP
^^%MTEXCH-E-QIO\\, ^COULDN'T POSITION TAPE. <QIO CALL FAILED.
.BR
.LM 12
^THE <QIO CALL TO POSITION THE TAPE FAILED.  ^THERE MAY BE INSUFFICIENT
QUOTA OR DYNAMIC MEMORY.
.LM 7
.SKIP
^^%MTEXCH-E-POSFAIL\\, ^COULDN'T POSITION TAPE. ^TAPE ERROR.
.BR
.LM 12
^THE MAGTAPE DRIVER COULD NOT POSITION THE TAPE AS REQUESTED.  ^THE DEVICE
MAY HAVE GONE OFF LINE OR THE TAPE POSITION WAS LOST.
.LM 7
.SKIP 3
^PROGRAM ^INSTALLATION AND ^MAINTENANCE:
.P
<MTEXCH IS WRITTEN IN <VAX NATIVE MODE ASSEMBLER.  ^IT USES <RMS RECORD
MODE <I/O TO THE DISK FILES AND <RMS BLOCK MODE <I/O TO TAPE.
<QIO LOGICAL <I/O CALLS ARE USED TO PERFORM THE POSITIONING
FUNCTIONS.    ^THE COMMANDS
ARE READ FROM THE LOGICAL NAME <SYS$INPUT AND MESSAGES ARE WRITTEN TO 
<SYS$OUTPUT.  ^THE PROGRAM IS INSTALLED SIMPLY BY ASSEMBLING AND LINKING IT
WITH A COMMAND SEQUENCE SUCH AS:
.INDENT 5
.SKIP
^^$MACRO/LIST MTEXCH
.INDENT 5
$LINK MTEXCH\\
.SKIP
^ONE OF THE GOALS CONSIDERED IN WRITING THIS PROGRAM WAS TO MAKE IT AS
EASILY EXTENSIBLE AS POSSIBLE.  ^AS SUCH, ADDITIONAL SWITCHES AND 
RECORD FORMATS SHOULD BE FAIRLY EASY TO IMPLEMENT.  ^AS USUAL, HOWEVER,
ONLY ENOUGH FEATURES WERE IMPLEMENTED TO ACCOMPLISH THE TASK AT HAND.
^COMMENTS AND SUGGESTIONS ON THIS PROGRAM ARE GREATLY ENCOURAGED.