1	AVATU

           Amdohl-Vax Ascii Tape Utility (AVATU)

     The purpose of the Amdohl-Vax Ascii Tape Utility is:

     1.  Allow a Vax system to read any IBM magtape which is
         written  only  with  the Ebcdic-Ascii character set
         (ie.  Ebcdic characters which  have  Ascii  equiva-
         lents)  and copy the magtape's contents into a disk
         file.

     2.  Allow a Vax system to write  any  Ascii  only  disk
         file onto a magtape in the appropiate format (Ebcd-
         ic) and content (labels,etc.) so that an IBM system
         can  read the magtape.  The magtape produced on the
         Vax system should not require any extra  considera-
         tion  than  one  which  is created on an IBM system
         when it is read on an IBM system.

     3.  Provide a general tape utility to  read  and  write
         any IBM (Ascii only) magtape on a Vax system.  This
         is accomplished by simulating  the  algorithms  the
         IBM system use to read and write magtapes.

     4.  Provide a resonable bulk  throughput  when  reading
         and writing magtapes.

2	USING
     Before using AVATU, mount the tape of interest /FOREIGN
on the magtape drive.
	
	$ MOUNT/FOREIGN/DENSITY=1600 MSA0: ANY_NAME
	
     After the magtape is successfully mounted, the AVATU is
invoked by entering the commands.

	$ AVATU:=$SYS$SYSDEVICE:[SYSUTL]AVATU
	$ AVATU  
	
AVATU will then prompt the user for further input.  AVATU's 
prompts adhere to the following conventions:

     1.  Along with each prompt, a list of acceptable inputs
         is  clearly  stated (if such a finite list exists).

     2.  For each prompt which has a default  (ie., if the user
         just hit the <cr> for input), the default condition 
	 is enclosed in square brackets within the prompt.   
2	PROMPTS
     AVATU will prompt the user several times before it  ac-
tually  starts to read/write the magtape.  The inputs to the
prompts will allow the utility to finalize the run-time par-
ameters.   The  following sections will describe each prompt
and its acceptable inputs.  Listed below  is  an  abreviated
summary of the prompts:
	
  Reading a magtape:

     1.  ENTER TRANSFER MODE:           (READ)
     2.  ENTER MAGTAPE UNIT NUMBER:
     3.  ENTER ESTIMATED FILE SIZE IN BLOCKS:
     4.  ENTER EXTENSION FILE SIZE IN BLOCKS:
     5.  ENTER VAX OUTPUT FILE NAME:
	
  Writing a magtape:

     1.  ENTER TRANSFER MODE:           (WRITE)
     2.  ENTER MAGTAPE UNIT NUMBER:
     3.  CREATE VOLUME LABEL?:
     4.  ENTER VOLUME SERIAL NUMBER:  (this prompt only if
                                       YES to previous prompt)
     5.  ENTER DATASET ID:
     6.  ENTER MAGTAPE BLOCK SIZE:
     7.  ENTER VAX INPUT FILE NAME:

     The first prompt upon a successful invoke of the  AVATU
utility  is  the  transfer  mode  prompt.  The transfer mode
prompt establishes to the utility whether the user is  read-
ing  or writing a magtape.  Two differnet set of prompts are
used depending on the transfer mode entered at this prompt.
	
	ENTER TRANSFER MODE:
	
The acceptable inputs are:

     1.  0 if the user wishes to read an IBM magtape.
     2.  1 if the user wishes to write an IBM magtape.
     3.  ^Z if the user wishes to exit the utility.

     The second prompt is always the  magtape  drive  select
prompt.   This  prompt makes known to the utility which mag-
tape drive it is supposed to use.  The magtape  of  interest
should  be  mounted  foreign on the magtape drive before the
utitly is invoked.
	
	ENTER MAGTAPE UNIT NUMBER:
	
The acceptable inputs are any of  the  legal  magtape  drive
names  (ie.   MSA0, MMSA1, etc.) on the system.  It should be
the same as the magtape drive name entered in the MOUNT com-
mand.

     Following the first two prompts above (which always ap-
pear  irregardless  of  the transfer mode) come the transfer
mode dependent prompts.  That is, a different set of prompts
is used depending if the magtape is being read from or being
written to.  The remaining  sections  are  divided  into  two
parts, each dealing with one set of prompts.

The magtape written on the Vax system  for  the  IBM  system
will always has the following characteristics:

     1.  Volume serial number -- user specified or  what  is
         originally on the magtape.
     2.  Dataset id -- user specified.
     3.  Dataset serial number -- 000000.
     4.  Creation date -- 00000.
     5.  Expiration date -- 98003.
     6.  System code -- blank filled.
     7.  Record format -- variable length format.
     8.  Block length -- user specified.
     9.  Record length -- largest record length in the  disk
         file.
     10. Block attribute -- blocked and spanned.
	
	CREATE VOLUME LABEL?:
	
This prompt is required due to the two types of magtape  the
user can use to run with the utility.

     1.  Magtape which already has a volume  label  already.
         (ie.   all  IBM cataloged magtapes will have volume
         labels already on them).

     2.  Magtape which does not have a volume  label.   (ie.
         a brand new magtape).

The acceptable inputs to this prompt is either a  YES  or  a
NO.   If  the  user  responds with a YES, then the following
prompts will appear, however, if a NO is entered,  the  next
prompt will not appear.
	
	ENTER VOLUME SERIAL NUMBER:
	
The acceptable inputs to this prompt is any  6-digit  number
which  serves  as  the  serial  number  of the magtape.  The
6-digit number will  be  written  onto  the  magtape  volume
label.  The user is adviced to remember this number since he
or she may need it on the IBM side to read the magtape.
	
	ENTER DATASET ID:
	
This prompt makes known to  the  utility  the  dataset  name
which it is going to write to the magtape.  The dataset name
is written onto magtape header label.   It  is  pointed  out
that the dataset id does not necessarily have to be the same
as the input file  name.   The  acceptable  inputs  to  this
prompt is any alpha-numeric (up to 17 characters - null pad-
ded) string.
	
	ENTER MAGTAPE BLOCK SIZE:
	
The bigger the block size is written  to  the  magtape,  the
smaller  the amount of magtape is used to write the same am-
ount of data.  However, it is recommended the largest  block
size  to  be  used  should be around 4000.  Using any larger
block size may use lesser amount of magtape, but  may  cause
system  complications at run-time.  The acceptable inputs to
this prompt is a number between 20 and 32768.
	
	ENTER VAX INPUT FILE NAME:
	
This prompt makes known to the utility the Ascii  disk  file
that  the user wishes to copy onto the magtape.  The accept-
able inputs to this prompt is any legal filespec of the  Vax
system.

     After the input to the last prompt,  the  utility  will
begin  to copy the disk file onto the magtape.  This utility
is capable of handling multiple dataset, mutiple volume mag-
tape  format.  When the utility finishes processing the cur-
rent disk file, it will prompt again for the next disk  file
to  copy  onto  the magtape by prompting for the dataset id.
If the user has more disk file to copy onto the magtape,  he
can  follow  the  above  sequence again.  if the user has no
more files to copy onto the magtape, the user  should  enter
^Z  to  exit  the utility (an end of volume label is written
onto the magtape in the exting process).  Entering  ^Z  will
cause  the utility to terminate and the DCL command level to
prompt.  When the utility terminates, the magtape will auto-
matically rewind to its BOT point.  The user should dismount
the magtape by using the DISMOUNT command.
	
	$ DISMOUNT MSA0:
	
The IBM magtape being read should have the following charac-
teristics in order for the utility to perform successfully:

     1.  Record format -- variable or fix length format.
     2.  Block   attribute   --    blocked    (spanned    or
         not-spanned).

After the magtape drive select prompt, the utility will  ac-
tually  read the magtape lead labels and display its info on
the screen.  The user after seeing the displayed  info  (vo-
lume serial number, dataset id, etc.) can either continue by
responding to further prompts or entering  ^Z  to  exit  the
utility (if the wrong magtape is mounted, ie.).  The displa-
yed info allows the user to double check  that  he  has  the
correct magtape.
	
	ENTER ESTIMATED FILE SIZE IN BLOCKS:
	
This prompt is here due to the fact that it is much more ef-
ficient  to  allocate the storage for a file once than it is
to allocate it many times.  So if the user knows the approx-
imate size of the file, he or she can enter the size at this
prompt to allocate this storage just once.   The  acceptable
inputs to this prompt is any number between 0 and 32768.
	
	ENTER EXTENSION FILE SIZE IN BLOCKS:
	
For the same reson as above, that is, efficiency, it is  de-
sirable to allocate extension file size in big enough chunks
so that the system does not has  to  extend  the  file  many
times (if it has to be extended, due to under estimated file
size in the above prompt).  The acceptable  inputs  to  this
prompt is any number between 0 and 32768.
	
	ENTER VAX OUTPUT FILE NAME:
	
This prompt makes known to the utility the file name of  the
output  file  the utility should write into.  The acceptable
inputs to this prompt is any legal filespec in the Vax  sys-
tem.

     The utility supports multiple dataset, multiple  volume
format.  Therefore, if the IBM magtape has more than one da-
taset on it, then the utility, when it  finishes  processing
the  first dataset, will again prompt for the estimated file
size, extension size, and the output file name for the  next
dataset.   The user can terminate the utility at any time by
entering ^Z as the reponse to a prompt.  If the utility  de-
tects  an  end of volume label, it will automatically termi-
nate.  When the utility terminates, it will rewind the  mag-
tape to its BOT point.  The user should dismount the magtape
by using the DISMOUNT command.
	
	$ DISMOUNT MSA0:
