FTPack 3R3D -- Utility to Pack Unisys Files for Transfer

   @FTPACK,options  Input-File.[elt], Output-File.[elt], ;
             Unpack-File/asg-opts/equip.title/initresv-packid(seq#), ;
             trks/wcnt/mspc.surv-intvl/pack-intvl(RecSz),split-info/extra-op

A - Survey entire file, regardless of size, rather than the default maximum of 5000 tracks. This will result in a more complete table of words and frequencies, with a resulting improvement in compression, but not necessarily so much as to make it worth the extra time.

B - Basic survey: only 100 tracks of the input, spread throughout the file. This will yield the quickest compression.

Both this value and the default value can be changed by modifying the tags DEFSRV and DEFBAS near the start of the FTPACK source and recompiling.

C - Pre-compress input file using SDFCOMP utility. See section on C-Option Pre-Compression. This is intended for a program file with source elements.

DKPQZ - Used with C. See C-Option Pre-Compression section.

E - No I/O trace escape sequences during input survey or output packing. Assumed if in batch, breakpoint, or @ADDed file.

F - Output is to be a standalone file vs. a self-extracting @ADD file. This can save space if there are many such outputs but they will each require an @FTPACK,U to unpack. Compare with X. Ignored if J option set or if splitting files.

Standalone files can have incompatibility problems with different levels of FTPack, so you should ensure the level that created them will be available to unpack it. There is no such problem with self-extracting files, which is why that method is the default.

G - Generate ECL to follow the output file. These images will be executed after the FTPack file is @ADDed and unpacked. Before closing the output file, FTPack will solicit the user for images. A blank in column 1 will cause an '@' to be inserted there for ECL commands; this master space character can be redefined by the mspc character in the 4th field.

HELP - Display a screen describing basic FTPack call, options, and fields.

HELPC - Display a screen describing pre-compressing the FTPack input file.

HELPS - Display a screen describing using FTPack to split a large file into two or more outputs.

I - Trace I/O every <25> tracks. If E, every 50, 100, 250, 500, or 1000 tracks depending on input size. This is the default in demand. Compare with T. In nonbreakpointed demand, escape mode will be used to generate an updating display on the last line of the screen. The E option will prevent this use of escape mode.

J - Join the FTPack of the input file to the end of the output file, which is assumed to be an FTPack file.

LM<H>VS - Output record size in characters: 80, 132, 3968 (the default). 7168, or 8188. To set a different value, see Spec 4.

N - No print except for end lines.

O - Override FTPACK/options default. The FTPack absolute may be renamed as FTPACK/xxx in its normal execution file or a user's file. "xxx" are the default options to use unless overridden. Example: FTPACK/TS. The renamed absolute can still be called as @<file>.FTPACK as long as there are no other FTPACK absolutes in the file.

R - Treat as raw file; make no tests for program, SDF or other type of file.

T - no I/O trace. Compare with I. If no I/O trace is being done in demand, an @@X C keyin may be done to force a one-time display of the current I/O trace.

U - Unpack the input file to the output file. For larger files, a "progress bar" will be generated in escape mode across the bottom line of the screen. This may be prevented with the E option.

One or more options may be combined with U:

UF - Force the unpack regardless of the state of the output file. Normally FTPACK will require that the output file be empty or a non-program file.

UG - Do not @ADD any post-unpacking ECL that may have been generated by the G or Q options.

UX - Unpack a selected file in a stacked FTPack file by title or sequence number, extracting the embedded unpack filename from the stacked file. In this instance there is no filename needed in Spec 2.

UN[LG] - List the contents of the input FTPack file only. If L option, print an additional line showing the source file if available. If G option, list any embedded and post-unpacking ECL. If the input file is stacked, all files will be listed.

W - Show the 64 most frequent coded words. A different number may be supplied in the 4th field.

X - Create a self-extracting file. This is the default. The FTPacked output file is preceded by an @ELT,IA of a compact version of FTPack whose only purpose is to unpack the following file when the FTPack file is @ADDed.

Input-file[.elt] - Any 2200 file or source element. Unless the R option is used, the file will be classified according to type: program, SDF, etc., or UNKNOWN.

Output-file[.elt] - The file or element into which the FTPack output will be written. If a file, it must be empty or a non-program file; otherwise an error message will be printed. This may be overridden with the F option.

If the output file is already in FTPack format, you will receive the following message in nonbreakpointed demand:

                    ** WARNING: OUTPUT IS SELF-EXTRACTING FTPACK FILE
                       -- JOIN, OVERWRITE, OR QUIT? - JOQ

Reply as needed. If it is intended to join the new output to the old one, use the J option to avoid the message.

In breakpoint or batch only the first line of the message will be displayed, and FTPack will default to overwriting the output file.

If the FTPack output is to an element, be aware if it may be large enough to require an LEPF. If an output element larger than 262143 sectors is written to a non-LEPF file, you will receive a warning message. The FTPack will complete, but the output will be usable only if the file remains intact. If the file is @PACKed, the output will be truncated and unusable.

[Unpack-File]/asg-opts/equip.title/initresv-packid(seq#)

The third field defines the file that will be created when the FTPack output is unpacked, either by @ADDing the FTPack output file or by an @FTPACK,U call.

"Unpack-File" denotes the Qualifier*Filename and optional F-cycle of the file.

The asg-opts/equip parameters, in the read/write key fields, specify the assign options and equipment type to use when assigning the file prior to unpacking. Asg-opts may have T for a temporary file, A for a file that already exists, or combinations like CP, UPR, CPI for files that do not yet exist. If asg-opts/equip is omitted it defaults to T/F.

If the entire Unpack-file/asg-opts/equip field is omitted, the temporary file FTUNPACKFILE will be assumed.

If the first option in asg-opts is C or U, Unpack-File may be omitted, signalling that the filename from Spec 1 of the @FTPACK call is to be used. In such a case, if the unpack file is unowned and was coded with read/write keys, they will be applied to the unpack file. But in any case, if the unpack file is to have different keys, use the G option on the @FTPACK call, and when prompted enter a @CHG command that will change the unpack file's keys. This command will be executed after the file is unpacked.

Title is a 1-12 character designation for the file. It will be attached as a @USE name to the unpack file after unpacking. If Unpack-file is omitted and asg-opts is missing or does not begin with C or U, title will be used for the filename. Title can also be used when extracting an individual file from a stacked FTPack file (see later section, Stacking Files).

The initresv-packid field may be used to specify an initial reserve for the unpack file and/or a packid if the file is to be removable. An initial reserve should rarely be necessary because FTPack will supply one based on the size of the input file. If both items are present they must be separated by a dash unless both are six characters. Either initresv or packid may appear by itself, but if the packid is by itself and begins with a digit, it must be preceded by a dash to distinguish it from initresv. If the input file is larger than 262143 tracks, initresv must be in positions.

Seq# is discussed under Stacking Files.

trks/wcnt/mspc.surv-intvl/pack-intvl(RecSz),

These parameters affect various performance and display options.

trks - The maximum number of tracks of the input to survey. Default: 5000. If the actual size of the input file is larger, FTPack will spread the survey over proportional intervals. Survey tracks may also be set by the A option (All) or the B option (100). Coding this number will override either option.

wcnt - The number of surveyed words to list sorted by descending frequency, showing which words occurred most often in the input. The W option sets this to 64. Default: 0. When wcnt is used, the W option is assumed.

mspc - An alternate master space character to use for '@' in column 1 for ECL images solicited by the G or Q option. The default is a space. Any other character in column 1 will be left as is, allowing data images to be included. mspc may be any valid write key character except '@'.

surv-intvl - The track interval at which FTPack displays a report of how much of the input has been surveyed, if I/O trace is being performed. Default: 25 in nonbreakpointed demand; 50, 100, 250, 500, or 1000 in batch or breakpoint, depending on the input size.

pack-intvl - The track interval at which FTPack displays a report of how much of the input has been packed. Default: same as surv-intvl.

RecSz - The record size in bytes (quarter words) of the packed output. Default: 3968. Range: 80 - 8188. Will be adjusted to a multiple of 4 as needed. Overrides the L, M, H, V, or S options.

This parameter is discussed in the Splitting Files section. Extra options are discussed in both that section and under C-Option Pre-Compression.

FTPack has additional capabilities beyond packing a single file.

Multiple files may be stacked in an FTPack output file. After one has been created, others may be added behind it by calling @FTPACK with the J option, or answering J to the warning message described under Output File. An additional advantage of stacking files is that only one copy of the unpack absolute is needed at the head of the file; it is used to unpack all the files in the stack. Example:

 @FTPACK   PROGFILE1.,PACKAGEFILE.,PF1
 @FTPACK,J PROGFILE2.,PACKAGEFILE.,PF2
 @FTPACK,J PROGFILE3.,PACKAGEFILE.,PF3
 etc.

A stacked FTPack file must be self-extracting, so if the F option was used when creating the first file in a stack, no other files may be joined to it. If the F option is used when joining subsequent files, it will be ignored.

All the files stacked in such a file may be recreated by @ADDing it. A list of all the files stacked in an FTPack output file may be displayed by calling @FTPACK against it with the U and N options. The L option will print an additional line showing the original source of each file.

Alternatively, you may extract individual files from the stack by using their title or sequence number. When listing a stacked file via @FTPACK,UN, each component file will be listed either by title or, if none was given, by the indicator '(UNTITLED)', with its sequence number on the right. If there are duplicate titles in a stacked file, only the first can be extracted by using the title; use the sequence number for the others. Examples:

 (Listing)


 @FTPACK,UNL STACKFILE.
 FTPack 3R3A [@FTPACK,HELP] -- 2016 Apr 09 Sat 1203:00
 PROG. FILE  LIB3        <-FTPACK 3R3A:2016-04-09,1148:08;OP=HX,RSZ=3968   #1
 >>> SOURCE: LCL*MYLIBS3(1). -- TRACKS: 142
 PROG. FILE  (UNTITLED)  <-FTPACK 3R3A:2016-04-09,1148:31;OP=HJX,RSZ=3968  #2
 >>> SOURCE: LCL*MISCELTS(1). -- TRACKS: 29
 END FTPACK. JCNT: 2


 (Unpacking)


 @FTPACK,U STACKFILE.,F1.,LIB3      . (single file by title)
 @FTPACK,U STACKFILE.,F2.,(2)       . (single file by sequence #)
 @FTPACK,UX STACKFILE.,,LIB3        . (title & extract filename)
 @FTPACK,UX STACKFILE.,,(2)         . (sequence # & extract filename)
 @ADD,L STACKFILE.                  . (all files)

For individual extraction the output files (in the first two examples, F1 and F2) must be pre-assigned, unless the embedded unpack filename is being extracted, as in the 3rd and 4th examples (LCL*MYLIBS3).

When unpacking an individual stacked file using the UX options to extract the embedded unpack filename, FTPACK will perform internally the @USE and the @ASG commands that would have been @ADDed prior to unpacking. If for some reason the internal @ASG is rejected, the FAC status will be displayed; and you will need to either correct the problem that caused the rejection, or @FTPACK,U the file to a different output.

FTPack can split a very large file into a maximum of 999 parts. This is specified in the 5th parameter field:

asgopts/equip/packid.splinf/extraopts

asgopts - Options for assigning the output split files. Default: CPI.

equip - Equipment for output split files. Default: F.

packid - Packid if split files are to be removable.

splinf - Information on how to split the file. This can be either a number indicating the track size of each split file, or an 'X' followed by the number of parts into which to split the file.

Split file parts may be either individual files or elements within a program file. If the latter, asgopts/equip/packid is ignored.

extraopts - Additional options affecting the operation:

L - List the generated @ADD file, FTPACK$ADD.

N - Do not @ADD the generated runstream. This allows the user to edit and modify the FTPACK$ADD runstream as needed before @ADDing it.

X - Do not take the default action of generating @ADD images for the 2nd thru last split parts at the end of the first.

FTPack will generate and @ADD a file containing an @FTPACK call for each part of the input. Unless the X extra option was used, you can recreate the original input by @ADDing the first split part.

FTPack appends sequence numbers to each split part at the lowest level of OutFl (filename, eltname, version), so the name used at that level must be short enough to accommodate a 1-, 2-, or 3-digit sequence number.

== Examples:

1. @FTPACK BigFile.,BIGPACK.,,,CPRVI/FMD/ARCH01.2000/L

Will split BigFile into BIGPACK1., BIGPACK2., etc. every 2000 tracks.

2. @FTPACK BigFile.,MY*ARCHIVE.XYZDATA,,,X20

Will split BigFile into 20 elements:

MY*ARCHIVE.XYZDATA01,.XYZDATA02,...,.XYZDATA20

Pre-compressing the source elements in a file can lead to a significantly smaller FTPack output. The utility SDFCOMP and its auxiliary SRCEXP - available at the same web site as FTPack - are expected to be in the FTPack execution file or in a file with the internal name FTPACK$C-OPT.

When a program file is @FTPACK,C, it is first copied to an intermediate file. Its source elements are compressed by SDFCOMP into the single element $CMP-SOURCE$, and the SRCEXP absolute is added to the file. These two, plus the original file's non-source elements, are then @FTPacked into OutFl. ECL is appended so that after the file is unpacked SRCEXP executes to expand $CMP-SOURCE$ back to the original source elts, SRCEXP is deleted, and the file is @PACKed. All this is accomplished thru an @ADD file, FTPACK$ADD.

Certain types of source elements may be rejected for compression by SDFCOMP. These include elements copied from print files, bulk-compressed program files, and elements with images longer than 252 characters. Starting with SDFCOMP 2R9B, by default these elements will be copied over to the intermediate file uncompressed, just as is done for absolutes and other non-symbolic elements. This copying can be prevented by the X extra option.

Additional @FTPACK options with C:

D - Destroy entry point table; after unpacking, @PACK vs. default @PACK,P.

K - The source elts to compress have been selected with the SORTOC utility; it must be in the same file as SDFCOMP, which will use the "/$" input option to select the files in SORTOC$PRT-T. Remaining source elements in the file are copied over as is unless the $ extra option is used.

P - Compress PROC as well as non-PROC elts. By default, PROCS are not pre- compressed and retain their procedure table entries. If P is used, PROCS are also compressed and must be re-@PDPd when unpacked. Overridden by K. Assumed if the file has no procedure tables.

Q - Query for ECL to insert before the final @PACK. (ECL solicited by @FTPACK,G is inserted after the @PACK.)

Z - Internally zero intermediate file rather than generate an @ERS for it.

The version field of Spec 5 may include extra options, just as for split files:

C - SDFCOMP option (list character sets).

F - SDFCOMP option (list character frequencies).

J - SDFCOMP option (if used with K Extra option).

K - SDFCOMP option (character mode vs. the default G [string mode]).

L - List the generated @ADD file, FTPACK$ADD.

N - Do not @ADD the generated runstream. This allows the user to edit and modify the FTPACK$ADD runstream as needed before @ADDing it.

P - Convert elements copied from print files to straight ASCII elements. This will prevent their being rejected, but they will lose all print file formatting and print control information.

Q - SDFCOMP option (list string length counts).

S - SDFCOMP option (list compression statistics & summary at end).

X - Do not @ADD a runstream that will copy rejected elements to the intermediate file.

$ - Compress only those source elements selected by @FTPACK,K; omit any others.

n - SDFCOMP monitor interval in seconds; max = 99.

(sl) - SDFCOMP string lines to list (elt cycle field); max = 99.