cpftape

cpftape restores members from an IEBCOPY PDS unload stored in a Hercules AWS tape image to ordinary Linux files.

It is the companion to cpttape:

• cpttape moves Linux files into an IEBCOPY-compatible PDS unload on AWS tape.
• cpftape reads that unload and restores its PDS members as Linux files.

The utility is intended primarily for moving source and other text files between Linux and MVS systems while preserving the structure and useful metadata of PDS members.

Usage

cpftape [options] tape.aws

By default, cpftape reads logical file 1 from an NL (no-label) AWS tape and restores members into the current directory.

For example:

cpftape source.aws

Restore into a separate directory and append .c to each restored filename:

cpftape --directory=restore --extension=c source.aws

If the output directory does not exist, cpftape creates it.

Tape selection

--label=NL|SL[,N]

Select the tape label convention and, optionally, the logical tape file number.

Examples:

cpftape --label=NL tape.aws
cpftape --label=NL,2 tape.aws
cpftape --label=SL tape.aws
cpftape --label=SL,3 tape.aws

The default is:

--label=NL,1

NL and SL are accepted without regard to case.

Only NL and SL tapes are supported by cpftape. BLP is intentionally not supported by this utility.

--volser=SER

For an SL tape, validate the volume serial number.

cpftape --label=SL --volser=ABC123 tape.aws

The VOLSER is folded to uppercase.

--volser is valid only with --label=SL.

--dsn=NAME

For an SL tape, select/validate the data set name.

cpftape --label=SL --dsn=USER.SOURCE tape.aws

The DSN is folded to uppercase. VTAPE applies MVS standard-label data-set-name comparison rules.

--dsn is valid only with --label=SL.

Output options

--directory=PATH

Write restored members into PATH rather than the current directory.

cpftape --directory=restore tape.aws

Missing directories in the path are created as needed.

--extension=EXT

Append an extension to each restored member name.

Both of these forms produce the same result:

cpftape --extension=c tape.aws
cpftape --extension=.c tape.aws

For a member named SOURCE, the resulting Linux filename is:

SOURCE.c

The extension is preserved as specified; it is not folded to uppercase.

--replace

Replace an existing Linux output file.

cpftape --replace --directory=restore tape.aws

Without --replace, an existing destination file is not silently overwritten.

Replacement is performed using a temporary file and rename so that an existing file is not partially destroyed if restoration fails.

--output-errors=warn|abort

Select how member-level output errors are handled.

cpftape --output-errors=warn tape.aws
cpftape --output-errors=abort tape.aws

warn is the default. An error restoring one member is reported and processing continues with later members when possible.

abort stops restoration after an output error.

--preserve-time

Set the Linux file access and modification time from valid ISPF/SPF member statistics.

cpftape --preserve-time tape.aws

When valid SPF date and time information is present, the restored file receives that timestamp. If usable SPF time information is unavailable, normal Linux file creation time behavior is retained.

--binary

Restore fixed-format records without text conversion.

cpftape --binary tape.aws

Binary mode is supported only for RECFM F and FB. Each logical record contributes exactly LRECL bytes to the Linux file:

• no EBCDIC-to-ASCII conversion;
• no trailing-blank removal;
• no newline insertion.

This is useful for data such as object decks where the PDS member contents must be preserved byte-for-byte.

--binary is rejected for V, VB, and U data sets.

Text restoration

Normal restoration is text oriented.

For F and FB data sets, each logical record is converted from EBCDIC to ASCII, trailing blanks are removed, and a single LF (\n) is appended.

For V and VB data sets, IEBCOPY/record control information such as BDWs and RDWs is removed by the underlying PDS reader. Each resulting logical record is then handled as text in the same manner: EBCDIC-to-ASCII conversion, trailing-blank removal, and one LF.

RECFM U is not a supported restoration format in the current version.

Character conversion uses the project’s EBCDIC conversion facilities. Characters that do not have a usable mapping in the active conversion table may be replaced during conversion.

Member names

Normal MVS member names are converted to Linux filenames while preserving their decoded case.

Names containing only the supported filename character set are used directly. The supported set includes letters, digits, and:

@ # $ _ -

PDS directory names that cannot safely be represented this way are encoded as a 17-character Linux name:

@XXXXXXXXXXXXXXXX

where the sixteen hexadecimal digits represent the original eight-byte PDS member name. This makes binary or otherwise unusual member names deterministic and reversible.

Aliases

PDS aliases are normalized before restoration.

If an alias has a corresponding real member with the same TTR, the alias is ignored and the real member is restored.

If one or more alias entries refer to a TTR for which no real member entry exists, one alias name is retained and restored as the member name. This permits data referenced only by an alias directory entry to be recovered rather than discarded.

Listing an unload

Use --list to inspect an IEBCOPY unload without restoring files:

cpftape --list tape.aws

Example output:

RECFM=FB  LRECL=80  BLKSIZE=3120  Members=00004

Name              Newname           TTR    Userid   Date       Time       Lines Level
MEMBER1           MEMBER1           000006 TCS3     2026/08/12 14:53:00       1 80:00
#CPTTAPE          #CPTTAPE          000008 TCS3     2026/08/12 14:59:00      10 80:00
ALIAS2            ALIAS2            00000A TCS3     2026/08/12 15:02:00       1 80:00
#CPFTAPE          #CPFTAPE          00000C TCS3     2026/08/13 09:11:00      21 80:00

The DCB attributes are shown once because they apply to the entire unloaded PDS. Member information includes the original name, resulting Linux name, TTR, and available SPF statistics.

--extension may be used with --list to preview the resulting filenames without restoring them.

Informational options

-h
--h
--help

Display usage information.

-v, -V, --version

Display the cpftape version.

--verbose enables additional diagnostics.

--quiet suppresses nonessential output.

--verbose and --quiet are mutually exclusive.

Examples

List the first data set on an NL tape:

cpftape --list tape.aws

Restore it into the current directory:

cpftape tape.aws

Restore C source into a new directory:

cpftape --directory=restore --extension=c tape.aws

Restore and preserve SPF modification timestamps:

cpftape --directory=restore --extension=c --preserve-time tape.aws

Replace existing restored files:

cpftape --directory=restore --extension=c --replace tape.aws

Read logical file 2 from an NL stacked tape:

cpftape --label=NL,2 --directory=restore tape.aws

Read an SL data set and validate its volume and data set identifiers:

cpftape \
    --label=SL \
    --volser=SRC001 \
    --dsn=USER.SOURCE \
    --directory=restore \
    tape.aws

Restore an F/FB member set as raw binary data:

cpftape --binary --directory=objects object.aws

Interoperability

cpftape is designed to read IEBCOPY PDS unload data produced both by MVS IEBCOPY and by the companion cpttape utility.

Testing has included:

• listing and restoring an MVS-generated IEBCOPY unload;
• NL tape operation;
• fixed and variable blocked PDS data;
• SPF statistics and timestamp preservation;
• PDS alias normalization;
• CPTTAPE-to-CPFTAPE round-trip restoration;
• successful loading of CPTTAPE-generated unloads by IEBCOPY on MVS.

The utilities operate on logical tape files through the VTAPE library; IEBCOPY parsing is handled by the VIEBCOPY library rather than by CPFTAPE itself.

Exit status

A return code of zero indicates successful completion.

A nonzero return code indicates an error such as an invalid command line, tape/VTAPE failure, invalid IEBCOPY unload, unsupported record format, or restoration/output failure.

Diagnostics are written to standard error.

Related components

cpftape is built on several components in the same library collection:

• VTAPE — AWS tape and MVS tape-label handling.
• VIEBCOPY — IEBCOPY unload parsing and member iteration.
• mvs_utils / mvs_datetime — MVS metadata and date/time handling.
• ebcdic_utils — EBCDIC/ASCII character conversion.

Its companion utility is cpttape, which performs the opposite operation by creating an IEBCOPY PDS unload from Linux files.

Current scope

The current version restores a complete PDS unload. Selective member restoration is not presently implemented.

The utility deliberately focuses on the common Linux/MVS interchange use case. Additional record-format behavior, member selection, and other restore policies can be added in future versions without changing the basic tape and IEBCOPY architecture.