AATAPE.HLP                                                          June 1991

                    COLUMBIA UNIVERSITY KERMIT DISTRIBUTION


The complete Kermit is divided into five reels of 9-track magnetic tape, Tapes
A through E.  Tape A contains Kermit versions for the more popular PCs
(MS-DOS, CP/M, Apple II, Commodore 64, etc), Tape B for the more popular
workstations, minis, and mainframes (DEC operating systems, IBM mainframes,
UNIX, etc), Tape C for less popular PCs, Tape D for less popular minis and
mainframes, and Tape E for online documentation plus utilitity programs
(including programs for reading tapes).  See the file AAFILES.HLP for an
explanation of where the files are and what they're called.

All tapes are 9-track, 1600 bpi, odd parity, 2400-foot half-inch reels.
Blocksize is marked on the external label, and will be between 2K and 10K
depending upon various factors.

Your tape is in one of the following formats, as you requested.  The format
should be clearly marked on the external label.

ANSI -- ANSI standard label, volume label KERMIT, ASCII encoding, format D,
  variable length records.  Readable by most computer systems, should be
  readable by all since it's a national standard format.  On VAX/VMS, readable
  with the DCL COPY command. The ANSI tape format is described in detail below.

OS -- IBM OS standard label, volume label KERMIT, EBCDIC encoding, format
  VB, variable length records.  Format described in detail below.  First file
  on OS tapes is a 370 assembly program to read OS tapes under CMS.
  For MVS, use JCL.

TAR -- Unix Tar format, 10K blocksize.  This format is used by Unix computers
  only.

All formats contain only "printable" files -- program source, binaries in
"hex" or other printably-encoded format along with conversion programs,
documentation, etc.

Each Kermit distribution tape, A-E, comes with a directory listing showing
names of all the files that are on it, in the order in which they appear on
the tape.  In addition, the file AAFILES.HLP lists the files and gives a
fuller explanation of the naming conventions, and some information about the
various Kermit implementations.

ANSI and OS are the two formats most commonly used for exchanging information
on tape between unlike systems.  These formats are now described in some
detail; in case you don't have a utility handy to read your ANSI or OS tape,
the following information should be sufficient to allow a programmer to write a
procedure to get the information from the tape.

- ANSI LABELED TAPES -

All systems are supposed to be able to read ANSI labeled tapes, which,
according to ANSI standard X3.27-1978: "Magnetic Tape Labels and File
Structure for Information Exchange", should be the universal medium for
exchange between mainframe computers.  Our tape is written on any of several
types of computers, including a VAX with Unix (using an ANSI tape-writing
utility) or a VAX with VMS (using the COPY command), and conform to the ANSI
standard, level 3.  The tape is written as follows:

              Tracks:  9
             Density:  1600 bits per inch
              Parity:  Odd
  Character Encoding:  ASCII (ANSI X3.4-1968)
        Block Length:  8192 (unless indicated otherwise on external label)

ANSI labels (each label is an 80-byte record, encoded in ASCII):

Each label begins with a 4-character identifier, like VOL1, HDR1, EOV1, etc.
- Volume label  (VOL1): Volume name is KERMIT, in character positions 5-10.
    The volume label appears only at the beginning of the tape.
- File Header 1 (HDR1): File name is in character positions 5-21.
- File Header 2 (HDR2): Record Format (F, D, or S) in 5 (it's always "D"),
                        Block length in 6-10, ASCII numeric, leading 0's.
                        Record length in 11-15, ditto.
  After HDR1 and HDR2 comes a single tape mark (tm) then the contents of the
  file, terminated by another tm.  The (HDR1, HDR2, tm, file data, tm) sequence
  is repeated for each file.  At the end of file, there may be EOF1 and EOF2
  labels followed by a tm; if present, they may be ignored.

- At the end of tape may be EOV1 and EOV2 labels to indicate end of volume.
  There is a double tape mark at the end of the tape.

Record Format: "D" -- variable length records with a 4-digit ASCII length field
  at the beginning of each record (the length includes the length field
  itself), line terminators stripped, and no record crossing a block boundary.
  The record may be padded at the end with 0 to 3 circumflex characters,
  which are NOT included in the length field.  A null record ("blank line")
  is indicated by "0004" followed immediately by the length field of the
  next line.  "F" (fixed length record) format, although simpler to read, is
  not used because the Kermit distribution will not fit on a 2400-foot
  fixed-block tape because of the space wasted by padding each record with
  blanks.  Only printable files (text, program source, text formatter source,
  or hex) are included on this tape. 

Record Length:  Variable, max 800 (no lines of text in Kermit distribution
  files are more than 800 characters long; very few are longer than 200).

Block length: Since 8192 is longer than the normal block length on some
systems, you may need special procedures to read the tape.  For instance, on
VAX/VMS, you must "MOUNT/BLOCK=8192/DENSITY=1600 MTA0: KERMIT" (not /FOREIGN).

DEC PDP-11s may have trouble with these tapes.  RT-11 doesn't support them.
In RSTS, MOUNT MM0:/FOR=ANS KERMIT (or ASSIGN MM0:.ANSI), and use PIP to read.
In RSX, MOU MM0:/OV=ID and use PIP to read.  In both RSTS and RSX, you may
have to extend PIP's buffer size:
  RSTS: $ def/com/sys pip lb:[1,2]pip.sav/lin=8228, $ pip sy:=mm0:k11???.*
  RSX:  >rem ...pip, >ins $pip/inc=50000, >pip sy:=mm0:k11*.*
Decode K11*.HEX files on RSTS with K11HEX.FTN or K11HEX.B2S, not K11HEX.BAS.

- OS STANDARD LABELED TAPES -

The tape is written on either a SUN 4/280 running Unix, using a local utility,
or an IBM 370-Series machine running VM/CMS, using MOVEFILE.  The tape may be
read on IBM OS or MVS systems using normal JCL procedures.  The tape may be
read on CMS using the program provided as the first file on the tape.

The tape is written as follows:

Tracks:   9
Density:  1600 bits per inch
Parity:   Odd

Character Encoding:  EBCDIC

Labels (each label is an 80-byte record, encoded in EBCDIC):
Each label begins with a 4-character identifier, like VOL1, HDR1, EOV1, etc.
  Volume label  (VOL1): Volume name is KERMIT, in character positions 5-10.
    The volume label appears only at the beginning of the tape.
  File Header 1 (HDR1): File name is in character positions 5-21.
  File Header 2 (HDR2): Record Format in 5 (it's always "V"),
                        Block length in 6-10, printable EBCDIC digits,
				      filled to 5 columns with leading zeroes.
                        Record length in 11-15, printable EBCDIC digits,
				      filled with leading zeroes.
			Blocking attribute in 39 (always "B").
  After HDR1 and HDR2 comes a single tape mark (tm) then the contents
  of the file, terminated by another tm.  Finally, there are EOF1 and
  EOF2 labels, also terminated by a tm.  The (HDR1, HDR2, tm, file
  data, tm, EOF1, EOF2, tm) sequence is repeated for each file.

  At the end of the tape there is a double tape mark.

Block Format: "B" -- Each block begins with a 4-byte length field (the
  length includes the block length field) which is the actual length
  of the block.  The length field is encoded as two binary bytes (high
  order byte first) followed by two zero bytes.  Following the length
  are as many records as will fit in the block; no record spans
  multiple blocks.

Record Format: "V" -- variable length records with a 4-byte length field
  at the beginning of each record (the length includes the length
  field itself), line terminators stripped, and no record crossing a
  block boundary.  The length field is encoded the same was as the
  block length field, above.  "F" (fixed length record) format,
  although simpler to read, is not used because the Kermit
  distribution will not fit on a 2400-foot fixed-block tape because of
  the space wasted by padding each record with blanks.

Record Length: Variable, maximum 800 bytes. (No lines of text or program
  source in the Kermit distribution are more than 800 characters long,
  indeed very few are more than 200.  All of the Kermit-370 files are 80
  bytes long.)

Block Length:  Maximum of 8192 bytes.

Only printable files (text, program source, text formatter source, or hex) are
included on this tape.

JCL FOR READING AN OS-FORMAT KERMIT TAPE ON AN IBM MAINFRAME:

Use this template for the JCL.  It must be replicated for each tape file
to be read:

//  EXEC  PGM=IEBGENER
//SYSPRINT DD  SYSOUT=A
//SYSIN    DD  DUMMY
//SYSUT1   DD  DSN=tapefilename,
//             UNIT=tapeunit,VOL=SER=tapevol,DISP=SHR,
//             LABEL=(filenum,SL,,IN)
//SYSUT2   DD  DSN=diskfilename,
//             UNIT=diskunit,VOL=SER=diskvol,DISP=(NEW,CATLG),
//             SPACE=(TRK,(20,20),RLSE)

where:

   "tapefilename" is the name of the data set on the tape
   "tapeunit"     is the installation's unit name for a tape drive
   "tapevol"      is the volume serial number of the tape
   "filenum"      is the sequence number of the data set on the tape

   "diskfilename" is the name the data set is to be on disk
   "diskunit"     is the installation's unit name for disk drives
   "diskvol"      is the volume serial number of the disk, if needed

For example, if the file IKTKER.INS (TSO Kermit installation instructions) is
the 176th file on tape B, which (like all Kermit tapes) has the volume label
KERMIT, the following JCL would read this file (you still have to fill in the
tapeunit, diskunit, and diskvol parameters appropriate to your site):

//  EXEC  PGM=IEBGENER
//SYSPRINT DD  SYSOUT=A
//SYSIN    DD  DUMMY
//SYSUT1   DD  DSN=IKTKER.INS,
//             UNIT=tapeunit,VOL=SER=KERMIT,DISP=SHR,
//             LABEL=(176,SL,,IN)
//SYSUT2   DD  DSN=IKTKER.INS,
//             UNIT=diskunit,VOL=SER=diskvol,DISP=(NEW,CATLG),
//             SPACE=(TRK,(20,20),RLSE)

READING OS-FORMAT TAPES UNDER VM/CMS

CMS does not come equipped with a utility to read groups of files from an
OS-format tape.  OS-format Kermit distribution tapes contain two such
utilities as the first two files on the tape.  Use CMS TAPE, FILEDEF, and
MOVEFILE commands to read these files from the tape, then use them to read the
other files automatically.

Method 1: VM version 4 or later.  Use the REXX Exec OSTAPE EXEC (the second
file on your OS-format tape).  This program can read groups of files
selectively from the tape.  Instructions for use are in comments at the top of
the OSTAPE EXEC.  OSTAPE EXEC was written by Bob Meizlik of Pan American World
Airways, Rockleigh, NJ, USA, December 1990.

To copy this program from tape to a CMS disk, issue the following commands:

      TAPE REW
      TAPE FSF
      FILEDEF  INMOVE TAP1 (RECFM VB LRECL 800 BLOCK 8192)
      FILEDEF OUTMOVE DISK OSTAPE EXEC A (RECFM VB LRECL 100)
      MOVEFILE

Then, to clear the FILEDEF's before you run the exec, say:

      FILEDEF * CLEAR

Method 2: Any version of VM.  Use the assembly language program SPROSC
ASSEMBLE, provided as the first file on the OS format tapes, to read selected
files from the tape.  CMS style help is included at the beginning of the file.

To copy this program from tape to a CMS disk, issue the following commands:

      TAPE REW
      TAPE FSF
      TAPE FSF
      FILEDEF  INMOVE TAP1 (RECFM VB LRECL 80 BLOCK 8160)
      FILEDEF OUTMOVE DISK SPROSC ASSEMBLE A (RECFM VB LRECL 100)
      MOVEFILE
      COPYFILE SPROSC ASSEMBLE A (RECFM F LRECL 80)

To generate this program enter the following CMS commands:

      ASSEMBLE SPROSC
      LOAD SPROSC
      GENMOD SPROSC
      NUCXLOAD SPROSC

You should now have a runnable module called SPROSC.  To install the files,
the installation tape must be attached as 181, which might look something
like the following (note that the method for mounting tapes is
site-dependent):

      SMSG BATCH SETUP NOTAPE
or
      SMSG BATCH SETUP VOL KERMCO NORING SECOND

Once you have the tape attached as 181 or TAP1, the following is an example
of correct syntax:

      SPROSC TAP1 = = (EOF 217 PREFIX IK

This command will load all files with names beginning "IK" from among the
next 217 files on tape 181.  If the tape is ANSI, the files will be
translated into EBCDIC.  If the tape is not labeled, SPROSC will halt.


[End of AATAPE.HLP]

