1 MAG
!
[7m MAG Directives [m	SET BLOCKSIZE nbytes	    SHOW
			SET RECORDSIZE nbytes	    HELP [topic]
  WRITE file		SET RECORDSIZE VARYING	    EXIT
  READ file		SET [MAG]TAPE device
			SET [NO]TRUNCATE	    MOUNT [device] [density]
  WRITE @file		SET ASCII or EBCDIC			[/NOWRITE]
  READ @file		SET [NO]BYTESWAP
			SET COLUMNS col1 col2	    DISMOUNT [/NOUNLOAD]
  SKIP nfiles		SET DEFAULT string
  REWIND		SET [NO]SPACES
			SET LINES nlines	    ctrl-B	ctrl-Y

To get a printed document about MAG, execute:

	$  PRINT  SYS$DISK:[VAX86A.NSWC]MAG.DOC
!
2 Overview
!
MAG is an NSWC-written utility used to read and write FOREIGN mag tapes.
Foreign  tapes  are  those  which are used to transfer data to or from a
non-VAX system. The MAG utility reads fixed-length, blocked records from
nine-track tapes to disk files, and writes fixed-length, blocked records
to nine-track tapes from disk files.  the disk files do not need to have
fixed-length records.

To use MAG, execute the sequence of commands:

	$ MOUNT /FOREIGN /DENSITY=nnnn  dev_name

	$ MAG  [qualifiers]

When you exit the MAG utility, the tape can be unloaded by executing:

	$ DISMOUNT dev_name

The default tape drive ('dev_name') is MFA0.
!
2 Help
!
IF YOU ARE CURRENTLY EXECUTING MAG:

	To get help on a MAG directive, enter at the MAG> prompt:

		MAG> HELP DIRECTIVE directive_name

	To get help on an option of the SET directive, enter:

		MAG> HELP DIRECTIVE SET option	
!
2 Directives
!
When run interactively, MAG displays the prompt:

	MAG>

at this point any MAG directive can be entered.  The directive can be ab-
breviated as much as desired, as long as the truncation is not ambiguous.
Comments can be entered on directive lines, following the  directive  and
any  parameters;  the comment must begin with an exclamation point ( ! ).

Any DCL symbols appearing in directives and delimited by apostrophes will
be translated by MAG. The translation will take place AFTER the directive
is echoed and/or listed.
!
3 Read
!
READ file_name

Copies the next file from the mag tape onto  the  disk  file  'file_name'.
If  the  disk file already exists, a new version is created.   The tape is
left positioned after the end of the file. It is the user's responsibility
to not attempt  to read beyond end-of-information on the tape.  All of the
SET directives (see below), except SET BLOCKSIZE, are relevant for a READ.
See the HELP text for 'ctrl-B' and ctrl-Y' for related information.

READ @indirect_file

Uses the disk file 'indirect_file' as a list of file names. Each record on
this file must contain, beginning  in the first column and extending up to
the first  blank column, the name of a disk file to be used as the operand
of a 'READ file_name' command as described above.  These indirect commands
are iteratively performed before the next regular command is prompted for.
Each record on 'indirect_file' is printed on the MAG listing,  preceded by
the string:
			indirect>

Records  beginning  with an exclamation point ( ! ) are printed but other-
wise ignored.
!
3 Write
!
WRITE file_name

Copies the contents of disk file 'file_name' to the magnetic tape. An end-
of-file is written following the data; the tape is left  positioned  after
this.  The following SET directives (see below) are relevant:

    SET BLOCKSIZE    SET RECORDSIZE    SET [MAG]TAPE    SET DEFAULT

See the HELP text for 'ctrl-Y' for related information.

WRITE @indirect_file

Uses the disk file 'indirect_file' as a list of file names.   Each  record
on  this file must contain, beginning in the first column and extending up
to the first blank column, the name of a disk file to be used as the oper-
and of a  'WRITE file_name'  command as described above.   These  indirect
commands  are  iteratively  performed  before  the next regular command is
prompted for. Each record on 'indirect_file' is printed on the MAG listing
preceded by the string:

	indirect>

Records beginning with an  exclamation  point ( ! ) are printed but other-
wise ignored.
!
3 Rewind
!
	Rewinds the magnetic tape.
!
3 Skip

SKIP file_count

	Skips the magnetic tape forward,  bypassing  one  or 
	more  files.  'file_count'  is an integer describing 
	the number of files to skip.  IT IS IMPORTANT TO RE-
	MEMBER THAT  'MAG'  DOES  NOT KNOW THERE THE END-OF-
	INFORMATION IS ON THE TAPE; IT IS THE USER'S RESPON-
	SIBILITY TO NOT SKIP BEYOND END-OF-INFORMATION.
!
3 Mount
!
MOUNT [device] [density] [/NOWRITE]

	Mounts a FOREIGN tape at the specified density (800,
	1600, or 6250).   The default density is 1600.  If a
	device name is specified, MAG will mount this device
	and  use  it for subsequent operations (see also the
	SET MAGTAPE directive, described below). If 'device'
	is not specified, the current device is mounted (the
	current device is initially set to MFA0: ).   If the
	/NOWRITE qualifier is used, MAG will not allow WRITE
	directives.  The parameters and qualifier can appear
	in any order.
!
3 Dismount
!
DISMOUNT
    or
DISMOUNT /NOUNLOAD

	Dismounts the tape currently on the tape drive which
	MAG is using  (by default this is MFA0: -- it can be
	changed using the  SET MAGTAPE  directive, described
	below).  If /NOUNLOAD is specified, the tape is log-
	ically dismounted, but physically left loaded on the
	drive.
!
3 Help
!
HELP [topic]
!
IF YOU ARE CURRENTLY EXECUTING MAG:

	To get help on a MAG directive, enter at the MAG> prompt:

		MAG> HELP DIRECTIVE directive_name

	To get help on an option of the SET directive, enter:

		MAG> HELP DIRECTIVE SET option	
!
3 Exit
	Terminates the  MAG  utility.   The magnetic tape is
	rewound.
!
3 Show
!
Displays a brief summary of the current state of the MAG utility.  The
information displayed is:

    * The device name of the magnetic tape drive in use.

    * The number of the next file to be processed on the tape.

    * The current blocksize and recordsize values.

    * The current settings of the various formatting options:

		ASCII or EBCDIC          SPACES or NOSPACES
       TRUNCATE or NOTRUNCATE    BYTESWAP or NOBYTESWAP

    * The current active values, if any, as specified in SET COLUMNS or
      SET LINES directives.

    * Current value, if defined, for the default file name specification,
      as entered in the SET DEFAULT directive.
!
3 Set
!
SET  option  value(s)

	Controls the settings of the various options  available
	in the MAG utility.  Once set, an  option  is in effect
	until it is changed.  Each option has  a  default which
	is in effect when MAG begins.
!
4 Blocksize
!
SET BLOCKSIZE n_bytes

	Sets the size of a physical  block,  in  BYTES, used
	when WRITEing tapes.  (MAG automatically senses  the
	blocksize when READing tapes.  The blocksize must be
	an even multiple of the recordsize.   The  blocksize
	default is 1280 bytes.
!
4 Recordsize
!
SET RECORDSIZE n_bytes
SET RECORDSIZE VARYING

	Sets the size, in BYTES, of each fixed-length logic-
	al record on the magnetic tape.  When READing,   the
	user  must  ensure  that the specified recordsize is
	correct; there is no information in the tape  blocks
	to enable MAG to  determine  the  correct recordsize
	to use.   When WRITEing, the  recordsize  must be as
	large as the actual records to be  written,  or  the
	records will be  truncated when written to the tape.
	The blocksize must be an even multiple of  the  rec-
	ordsize.  The default recordsize is 80 bytes.

	If the keyword VARYING is used when READing, the en-
	tire block will be treated as one record, regardless
	of its length.
!
4 Magtape
!
SET MAGTAPE device
	or
SET TAPE device

	Sets the device name of the magnetic tape unit which
	MAG will read from and write to.  The default device
	is MFA0: .
!
4 Truncate
!
SET TRUNCATE
SET NOTRUNCATE

	Determines if,  on READs,  MAG  will strip rightmost
	blanks from each record.  Truncation should be  used
	whenever possible, in order to conserve disk storage
	space; the default is TRUNCATE.
!
4 Ascii
!
SET ASCII
SET EBCDIC

	Determines, on READs, the conversion to be performed
	on each character as it is read from the tape.   The
	default mode, ASCII, causes  no  conversion  to take
	place;  each byte is copied as it occurs on the tape
	record.  The EBCDIC mode causes characters to under-
	go EBCDIC-to-ASCII conversion  when  read  from  the
	tape.
!
4 Ebcdic
!
SET ASCII
SET EBCDIC

	Determines, on READs, the conversion to be performed
	on each character as it is read from the tape.   The
	default mode, ASCII, causes  no  conversion  to take
	place;  each byte is copied as it occurs on the tape
	record.  The EBCDIC mode causes characters to under-
	go EBCDIC-to-ASCII conversion  when  read  from  the
	tape.
!
4 Columns
!
SET COLUMNS col1 col2
SET COLUMNS

	Controls, on READs, the range of columns  (character
	or byte positions) on each input record that are  to
	be copied as the disk file output record.   All col-
	umns  outside  of the specified range are discarded.
	The default option is to include ALL columns of  the
	input records.  Once a rang of columns has been set,
	using for example SET COLUMNS 1 40, the default  can
	be restored by entering SET COLUMNS with  no  column
	numbers.
!
4 Lines
!
SET LINES nlines

	Specifies that READs are to stop after  transferring
	the  stated number of lines.   The tape is left pos-
	itioned at the beginning of the next file. If a zero
	value or no value is given for 'nlines', the default
	condition (READing entire files) is restored.
!
4 Default
!
SET DEFAULT string

Specifies parts of a file name to be used as default values when the co-
rresponding parts are omitted from READ and WRITE directives.  The parts
can include device name, directory, file name, file type and/or version.
Parts  for  which no default value is desired can either be omitted from
'string' or specified as a wild-card.  For example, if the directives:

	MAG> SET DEFAULT [MYDIR]DATA.DAT
	MAG> READ 001
	MAG> READ [YOURDIR]
	MAG> SET DEF LOGNAME:*.LIS
	MAG> READ A

are executed, the disk files created would be:

	[MYDIR]001.DAT
	[YOURDIR]DATA.DAT
	LOGNAME:A.LIS

Initially, there are no defaults for any parts of a file name; this con-
dition can be restored by entering SET DEFAULT with no string specified.
!
4 Spaces
!
SET SPACES
SET NOSPACES

	Determines, on WRITEs, whether tabs are converted to
	blanks.   The default is  NOSPACES, which causes the
	tabs to remain unconverted.
!
4 Byteswap
!
SET BYTESWAP
SET NOBYTESWAP

	Determines whether, on READs and WRITEs,  data bytes
	in each  odd-even pair of bytes in every tape record
	are to be transposed;  in other words,  if the order
	of  bytes  in  an input record is (1,2,3,4,5,6,7,8),
	then the order on the resulting output record,  when
	SET BYTESWAP is in effect, will be (2,1,4,3,6,5,8,7).
	The default is NOBYTESWAP.
!
2 Errors
!
If  mag  is  not  being  executed interactively, it aborts on an error.
Otherwise, the user can (in most cases) attempt to retry the operation.
!
3 Exit_status
!
Upon a normal exit (i.e. not via CTRL/Y), MAG's exit status will be one
of the following (in hexadecimal):

    00000001    (SS$_NORMAL)    For a normal exit.

    10000004    (Severe Error)  If MAG aborted on an error when not be-
                                ing  run  interactively,  or if  a non-
                                recoverable error  occured in an inter-
                                active run.

    10000000    (Warning)       If  no error occurred,  but one or more
                                files read from the tape were empty.
!
3 OPINCOMPL
!
An "Operation Incomplete" error could be caused by one of the following
three conditions:

   1. Attempting to read a tape which was written in a density not sup-
      ported on this tape drive (e.g. trying to read a 6250 bpi tape on
      a TU77 or trying to read an 800 bpi tape on a TU78).

   2. Attempting to read a tape which is blank.

   3. A Hardware malfunction in the tape drive.  Please notify the Sys-
      tem Manager if you think this is the case.
!	
3 WRITELOCK
!
A tape is "Write Locked",  and cannot be written to,  if either or both
of the following conditions hold:

   1. The tape does not have a Write-Protect Ring installed.

   2. The tape was MOUNTed with the /NOWRITE qualifier.

To remove the Write Lock condition, you must DISMOUNT the tape, install
a ring  (if necessary)  and re-MOUNT then tape.  You can do all of this
without exiting MAG by using the DISMOUNT and MOUNT directives.
!
2 ctrl-B
!
When doing a READ from a tape, at any time you may enter a CTRL-B character,
at which time MAG will display the size, in bytes, of the  last  tape  block 
read and the largest tape block read up to this point.
!
2 ctrl-Y
!
When a READ or a WRITE is in progress,  and you enter a  CTRL-Y  or a CTRL-C
character,  MAG will not abort.   Instead, it will act as if end-of-file had
been reached.  It will display the final block and record counts, and return
to the  MAG>  prompt for further commands.  The position of the tape will be
indeterminate.   The first directive you enter should be REWIND or EXIT.
!
2 Qualifiers
!
/INPUT

        /INPUT=in_file

Where:

         in_file  is the file containing directives to control the operation
                  of MAG.  By default, MAG reads directives from  SYS$INPUT.
                  if /INPUT is specified, the default file name and type are
                  MAG and .INP respectively.
!
/LISTING

        /LISTING=list_file

Where:

       list_file  is the listing produced by MAG.   By default, no  separate
                  listing is created;  MAG  does, however, always write this
                  same information to SYS$OUTPUT whether or not /LISTING  is
                  specified.   If it is specified, the default file name and
                  type for the listing file are MAG and .LIS .
!
/BUFFER

        /BUFFER=max_size

Where:

        max_size  is the size, in bytes, to be used for MAG's buffer.   This
                  value must be equal to or larger than the largest block to
                  be read from or written to tape.  If this qualifier is not
                  present, a value of 10000 bytes is used.
!
!
!			sgs_version = "3.0"
!
