CPTTAPE

CPTTAPE creates an IBM IEBCOPY-compatible PDS unload tape image from ordinary host files. It builds a temporary virtual 3350 DASD/PDS, places the input files into that PDS as members, and uses VIEBCOPY and VTAPE to write the unload to a Hercules-compatible AWS tape image.

CPTTAPE is intended primarily for moving files from a Linux host into an MVS environment. It supports both NL (no labels) and SL (IBM standard labels), including stacked logical tape files.

Features

• Creates IEBCOPY PDS unloads in Hercules AWS format.
• Supports RECFM=F, FB, V, VB, and U.
• Supports NL and IBM standard-label (SL) tapes.
• Supports stacked logical files with --label=NL,n and --label=SL,n.
• Automatically initializes a new SL AWS volume.
• Honors SL expiration protection when replacing existing tape files.
• Supports explicit expiration dates (--expdt) and retention periods (--retpd).
• Allows an unexpired SL volume to be extended by appending the next file.
• Generates old-style SPF statistics by default.
• Can preserve the intermediate VDasd image for examination or debugging.

CPTTAPE intentionally exposes only NL and SL processing. BLP is available in the underlying VTAPE library for utilities that require raw tape access, but it is not appropriate for CPTTAPE.

Basic usage

cpttape [options] input-file...

The default output file is cpttape.aws.

For example:

cpttape --output=source.aws one.asm two.asm three.asm

creates an NL AWS tape containing an IEBCOPY unload with one PDS member for each input file.

PDS member names

Member names are derived from the basename of each input file. The final filename extension is removed, the name is converted to uppercase, and at most eight characters are retained.

hello.asm       -> HELLO
test01.txt      -> TEST01
longmember.asm  -> LONGMEMB

If two files produce the same member name, the default is to keep the first and issue a warning. Use --duplicates=error to make this an error.

Record formats

The default is:

RECFM=FB
LRECL=80
BLKSIZE=3280

Supported formats are:

Example:

cpttape --recfm=FB --lrecl=80 --blksize=6160 --output=source.aws *.asm

Keyword values are case-insensitive, so --recfm=vb and --recfm=VB are equivalent.

NL tapes

NL is the default label type.

Create or replace logical file 1:

cpttape --output=backup.aws --label=NL,1 *.asm

Append file 2:

cpttape --output=backup.aws --label=NL,2 *.txt

Tape file numbering follows sequential tape rules. You may replace an existing file or append the next file, but you cannot skip nonexistent files. If a tape contains files 1 and 2, writing file 4 is an error.

Replacing an existing file truncates the volume at that point. If files 1, 2, and 3 exist and CPTTAPE writes file 2, the old files 2 and 3 are lost.

Standard-label (SL) tapes

SL output uses IBM standard labels, including VOL1, HDR1/HDR2, and EOF1/EOF2 processing.

A new SL volume requires a VOLSER and DSN:

cpttape \
  --output=backup.aws \
  --label=SL,1 \
  --volser=BK0001 \
  --dsn=USER.BACKUP.SOURCE \
  *.asm

CPTTAPE folds VOLSER and DSN to uppercase. If the AWS file does not exist, VTAPE initializes the SL volume automatically.

For an existing SL volume, --volser is optional. If omitted, the VOLSER in VOL1 is used. If supplied, it must match the existing VOLSER.

Append file 2:

cpttape \
  --output=backup.aws \
  --label=SL,2 \
  --dsn=USER.BACKUP.TEXT \
  *.txt

Expiration protection

An unexpired SL volume may be extended by appending the next logical file, but an existing file cannot normally be replaced.

To deliberately override expiration protection:

cpttape \
  --output=backup.aws \
  --label=SL,1 \
  --dsn=USER.NEW.BACKUP \
  --override-expiration \
  *.asm

Remember that replacing a logical file discards that file and all files after it.

EXPDT and RETPD

Specify an explicit SL expiration date with either:

--expdt=YYDDD
--expdt=YYYY/DDD

The five-digit YYDDD form always means a year in the 1900s. For example, 26365 means 1926 day 365. Dates after 1999 must therefore use the four-digit form, such as 2026/365.

IBM permanent-retention values 99365, 99366, 1999/365, and 1999/366 are accepted and treated as never expiring. 1999/366 is a deliberate tape-label special value even though 1999 was not a leap year.

where DDD is the day of year.

Or specify a retention period:

--retpd=30

CPTTAPE uses the mvs_datetime library to obtain the current date and add the requested number of calendar days, including correct year rollover and leap-year handling.

--expdt and --retpd are mutually exclusive. RETPD accepts 0 through 9999 days.

Input handling

Input data is not case-folded by default. Use:

--fold=upper

to convert input text to uppercase.

Long records are rejected by default. Use:

--long-record=truncate

to truncate them instead.

Duplicate member names are ignored with a warning by default. Use:

--duplicates=error

to make duplicates fatal.

Per-file input errors produce warnings by default. Use:

--input-errors=abort

to stop processing on an input error.

SPF statistics

Old-style SPF statistics are generated by default.

Disable them with:

--spf-stats=no

The default SPF user ID is CPTTAPE. Change it with:

--spf-user=USERID

The SPF user ID is folded to uppercase.

Temporary DASD image

CPTTAPE creates a temporary virtual DASD/PDS while constructing the unload. It is normally removed automatically.

Preserve the completed VDasd image with:

--keep-vdasd

or give it a pathname:

--keep-vdasd=mydisk.vdasd

Use --preserve to preserve temporary files after a failure for debugging.

Command-line options

Output and temporary files:
  --output=FILE                 output AWS image (default cpttape.aws)
  --preserve                    preserve temporary files after failure
  --keep-vdasd[=FILE]           preserve the completed VDasd image

Tape and PDS attributes:
  --label=NL|SL[,N]             tape label and file number
  --volser=SER                  SL volume serial (new SL volume requires it)
  --dsn=NAME                    SL data set name (required for SL output)
  --expdt=YYDDD|YYYY/DDD         SL expiration date
  --retpd=NN                    SL retention period in days (0-9999)
  --override-expiration         permit replacement on unexpired SL volume
  --recfm=F|FB|V|VB|U          record format (default FB)
  --lrecl=N                     logical record length
  --blksize=N                   physical block size
  --dir-blocks=N                allocated PDS directory blocks

Input policy:
  --fold=no|upper               data case folding
  --long-record=reject|truncate long-record handling
  --duplicates=ignore|error     duplicate member handling
  --input-errors=warn|abort     per-file input error handling

SPF statistics:
  --spf-stats=yes|no            generate old-style SPF statistics
  --spf-user=NAME               SPF user ID (default CPTTAPE)

Other:
  --verbose
  --quiet
  --help
  -v, -V, --version

--verbose and --quiet cannot be used together.

More examples

Create a basic NL unload:

cpttape --output=source.aws *.asm

Create an FB/80 unload:

cpttape --output=source.aws --recfm=FB --lrecl=80 --blksize=6160 *.asm

Create a new SL volume with a 30-day retention period:

cpttape \
  --output=source.aws \
  --label=SL,1 \
  --volser=SRC001 \
  --dsn=USER.SOURCE.PDS \
  --retpd=30 \
  *.asm

Append a second SL file:

cpttape \
  --output=source.aws \
  --label=SL,2 \
  --dsn=USER.TEXT.PDS \
  --retpd=30 \
  *.txt

Important tape behavior

CPTTAPE models sequential tape behavior. An AWS image is not treated as a collection of independently replaceable files.

• Writing an existing logical file replaces it and discards everything after it.
• Appending is allowed only at the next logical file position.
• Logical file numbers cannot be skipped.
• An unexpired SL volume may be extended, but existing files are protected unless expiration is overridden.
• If an error occurs after output to an existing volume has begun, the AWS image may already have been modified. CPTTAPE does not delete a pre-existing AWS image after such a failure.

These rules intentionally reflect the destructive, sequential nature of real tape processing.

Project libraries

CPTTAPE is built on the companion libraries in this project:

• VDASD — virtual DASD support.
• VPDS — PDS creation and directory/member handling.
• VIEBCOPY — IEBCOPY unload generation.
• VTAPE — NL/SL logical tape-volume and file processing.
• VAWS — Hercules AWS tape-image access.
• mvs_types — MVS-oriented data types and structures.
• mvs_datetime — MVS date handling and calendar arithmetic.
• ebcdic_utils — ASCII/EBCDIC CP037 conversion and related utilities.

Version

This README describes the completed CPTTAPE V1.0.1 NL/SL implementation baseline.