The REP Tool

This tool provides a fast, easy, and consistent way for copying files on MPE/iX. REP copies TurboIMAGE databases and KSAM files (for both native and compatibility modes), as well as standard MPE files.

Operation

File copying (next to file listings via LISTF) is perhaps one of the most common tasks anyone has to perform on the HP3000. REP can be used for virtually all of your file copying needs.

Standard MPE Files

REP has several options that can be used to tailor its operation to your exact needs. Option include: the initial number of extends, max extends, filecode, crunch, and xlcrunch.

Database Files

REP will copy entire TurboIMAGE databases (root file and datasets) just by specifying the root file. The option ROOTONLY will make REP copy only the root file and not the datasets. The DBSTORE option can be used to update the database timestamp and store flag.

Batch

When REP is run in batch, then it assumes that you always want to purge the old copy of the destination file, should one exist.

Capabilities

Program capabilities required include IA, BA, PM, DS and PH. No special user capabilities are required to use REP.

Usage

REP can be run from the supplied UDC or with a fully-qualified RUN statement.

UDC

REP [<inputfile> [[,] <outputfile>] [-] [<option>[,]...] [;parm=#]

RUN

RUN REP.PUB.LPSTOOLS;info="[<inputfile> [[,] <outputfile>] [-]

[<option>[,]...]" [;parm=#]

The "-" is optional when both an inputfile and an outputfile are present, and is required to signify the start of the option list if an output file is omitted.

In both modes, if the input file name has a group (or group & account) specified, then the default output file name is the input name without the group.account. For example, if the input file name is FOO.FIE.FUM, then the default output file name is FOO.logongroup.logonacct and will be used as the output file name if you hit "return" when prompted.

If you are using NS/3000, the inputfile and outputfile file names are allowed to have nodenames (i.e.: rep fun:fozzie, localfun).

File equations can be used for either the input or output files (or both).

Options Summary

The following table provides a summary description od REP options, which can be used to quickly locate the command that suits the task at hand. Detailed information on each option is provided in the next section.

Table 15.1 REP Options

Option	Description
CODE	Specifies filecode for output file.
[NO]CRUNCH	Closes output file with crunch disposition.
DBSTORE	Updates timestamp and store flag database copies.
DELAY	Pause during copy operation.
DEVICE	Specifies outfile device.
DISABLESTAR	Tells REP not to print "*" in quiet mode.
DOTS	Displays progress "dots" on screen during copy.
EXTENTS	Initial extents for output file.
FILECODE	Specifies filecode for output file.
KEYFILE	New keyfile for KSAM file copies.
LDEV	Specifies disk drive for output file.
LOCAL	Use logon group and account names for output file.
MAXETENTS	Specifies maximum number of extents for output file.
NOKSAM	Copies KSAM file as non-KSAM file.
NULL	Does not perform copy, creates output file.
[NO]PURGE	Overwrites (purges) output file if it exists.
[NO]QUIET	Suppresses some messages.
[NO]ROOTONLY	Only copies rootfile of database.
[NO]TEMP	Creates output file in temporary domain.
[NO]TIMES	Displays CPU usage.
[NO]XLCRUNCH	Closes output file with xlcrunch disposition.
YES	Overwrites (purges) output file if it exists.

The following PARM bits are recognized by REP as synonyms for some of the keyword options:

Table 15.2 PARM bits for REP

Bit#	PARM	Equivalent Option	Meaning
15	1	PURGE	You want to purge OLD destination files.
14	2	LOCAL	Target file is the same file-part name, but in logon group and account.
13	4	QUIET	You don’t like informative messages.
12	8	ROOTONLY	You don’t want to copy entire databases.
11	16	TIMES	You want CPU and elapsed times shown
10	reserved
9	64	DOTS	You want to see progress dots ".".
8 .. 0	reserved, should be 0

PARM options may be combined by adding their respective values.

Options Definitions

Following is a detailed description of each of the REP options.

CODE

This option has the following syntax:

CODE = <filecode>

By default, REP gives the output file the same filecode as the input file. However, the filecode can be specified as another type if you wish. See Appendix B for a list of the most commonly used filecodes. (This option and the FILECODE option are identical in operation.)

[NO]CRUNCH

This option causes the output file to be closed with "crunch" disposition, which sets the file limit to the file eof.

NOCRUNCH (default) tells REP not to crunch the output file.

DBSTORE

This option tells REP to update the timestamp & store flag that are stored in a database's rootfile. Normally, this operation is done by the DBSTORE program when a database is stored off to tape. However, users may want these flags when a database is duplicated.

The timestamp is used by DBRECOV to help identify the correspondence between logfiles and backup databases. See the TurboIMAGE/iX Database Management System Reference Manual - DBSTORE section for more details.

DELAY

This option has the following syntax:

DELAY [=#]

During large copy operations this statement will cause REP to pause between chunks (where a chunk is part of a file that was copied). A desirable side effect to using this option is that it keeps REP operations from starving other processes that are running at that time. Of course, using this option will cause the overall time required to copy the file to increase. However, other users on the system will be happy that you did! The delay is specified in milliseconds. If the DELAY option is specified without a delay number, 10 milliseconds will be used.

DEVICE

The DEVICE option has the following syntax:

DEVice = devicename

Specifies the devicename that the output file should be placed on.

DISABLESTAR

When REP is used in QUIET mode it displays an asterisk (*) to indicate that it has finished copying the file. However, there may be times that this is undesirable, so if you specify this option the asterisk (*) will not be displayed at the end of the copy. Situations when it is desirable include calling REP programmatically to perform a copy and you wish to keep display output to a minimum.

DOTS

Specify this option if you would like to display progress dots "." as it proceeds through a copy operation. The default option setting is to not print progress dots.

EXTENTS

This option has the following syntax:

EXTENTS = #

Specifies the initial number of extents to allocate for the output file.

FILECODE

This option has the following syntax:

FILECODE = <filecode>

REP normally gives the output file the same filecode as the input file. However, the filecode can be specified to another type if you wish. See Appendix B for a list of most commonly used filecodes. (This option and the CODE option are identical in operation.)

KEYFILE

This option has the following syntax:

KEYFILE = filepart

Specifies the name of the new key file for KSAM output files. The filepart may not have a group or account.

LDEV

This option has the following syntax:

LDEV = ldev#

Specifies the disk drive the output file should be placed on.

LOCAL

Output filename is the same file-part name, but in the logon group & account.

MAXEXTENTS

This option has the following syntax:

MAXEXTENTS = #

Used to specify the maximum number of extents for the output file.

NOKSAM

Tells REP to copy a KSAM file as a non-KSAM file.

NULL

This option causes the output file to be created and the space to be allocated, however no actual file transfer is performed.

[NO]PURGE

PURGE tells REP that it is ok to purge any existing file with the same name as the output file. NOPURGE tells REP that it must ask for permission to purge.

[NO]QUIET

QUIET Tells REP to suppress some output messages.

[NO]ROOTONLY

ROOTONLY tells REP to not copy an entire database when it is given a root file. NOROOTONLY (default) tells REP to automatically copy the entire database when given a root file.

[NO]TEMP

TEMP tells REP to leave the output file in the job/session temp domain. NOTEMP tells REP that the output file should be permanent. The default is TEMP if the input file is a temporary file, and NOTEMP otherwise.

[NO]TIMES

TIMES tells REP to report the CPU and Elapsed time that a file copy took. NOTIMES suppresses the time report.

[NO]XLCRUNCH

XLCRUNCH tells REP to close the output file with the new "xlcrunch" disposition. This tells the file system to discard any unused disc space past the EOF but does not set the file limit down to the file eof. Thus, an xlcrunched file is expandable later.

YES

The YES option is a synonym for PURGE. YES tells REP that it is ok to purge old files with the same name as the output file.

TOOLBOX STANDARDS

The ToolBox collections from Lund Performance Solutions have a uniform user interface. As a result, in addition to the commands specific to each Toolbox tool, most tools allow the commands described in "TOOLBOX STANDARDS".

REP Examples

Following are examples of the REP tool.

Figure 15.1 Specify Different Filecode

Figure 15.2 XLCRUNCH Copy

The next example copies TESTDOC.FUM.LPSTOOLS to TESTDOC.PUB.LPSTOOLS.

Figure 15.3 REP Example 1

The following example copies FOO.FUM.LPSTOOLS to FOO.PUB.LPSTOOLS.

If interactive, and FOO.logongroup.logonacct (in this case, FUM.LPSTOOLS) already exists, REP will ask for permission to purge it.

Figure 15.4 REP Example 2

The next example copies FOO.FUM.LPSTOOLS to FOO.PUB.LPSTOOLS, automatically purging FOO.FUM.LPSTOOLS, if it existed.

Figure 15.5 REP Example 3

The next example copies FOO.FUM.LPSTOOLS to FOO.PUB.LPSTOOLS, automatically purging FOO.logongroup.logonacct, if it existed.

Figure 15.6 REP Example 4

The next example copies FOO.FUM.LPSTOOLS to FOO.PUB.LPSTOOLS, automatically purging FOO.FUM.LPSTOOLS, if it existed.

Figure 15.7 REP Example 5

REP Error Messages

Each REP error message is described in the following table.

Table 15.3 REP Error Messages

Message	Cause	Action
Copying from $NULL is illegal!	Bad source (i.e., FROM) filename.	The FROM file must be a file that exists in the permanent or temporary domain.
Identical FROM file and TO file names are not allowed!	Bad choice of name for either the FROM or TO file.	Change either the FROM or the TO filenames to a different name.
IMAGE root files and datasets may not have lockwords.	Lockwords were discovered on either the Image rootfile or dataset.	REP does not support copying Image files with Lockwords.
TO file may not be a system file (except $NULL or $NEWPASS).	User specified a destination filename that was neither $NULL nor NEWPASS.	Enter a valid destination filename.