Invokes the Convert utility (CONVERT) to copy records from
one file to another, changing the organization and format of
the input file to those of the output file. For a complete
description of the Convert utility, including more
information about the CONVERT command and its qualifiers, see
the OpenVMS Record Management Utilities Reference Manual.
Format
CONVERT input-filespec[,...] output-filespec
1 – Parameters
input-filespec [,...]
Specifies the file or files to be converted. You may specify
multiple input files but wildcard characters are not allowed.
Multiple input files are concatenated to form a single output
file.
output-filespec
Specifies the output file for the converted records. If you omit
the file type, the Convert utility assigns the output file the
file type of the first input file. No wildcard characters are
allowed.
2 – Qualifiers
2.1 /APPEND
Controls whether converted records from an input file are
appended to an existing sequential file.
Format
/APPEND
/NOAPPEND (DEFAULT)
The /APPEND qualifier is useful when you want to convert an
existing file to the format of an existing output file and append
the converted records to the existing output file.
If you specify the /APPEND qualifier and the /CREATE qualifier,
/APPEND overrides the /CREATE.
You should use this option when you are loading records into
a sequential file that already contains records, or when you
are creating a new sequential file. When the output file is a
direct access file (relative or indexed), the /APPEND qualifier
is ignored.
2.2 /CREATE
Determines whether the Convert utility creates a file or uses an
existing file for output.
Format
/CREATE (DEFAULT)
/NOCREATE
The /CREATE qualifier causes the Convert utility to create an
output file instead of using an existing file for output.
If the output file is to have different characteristics from the
input file, you must also specify the /FDL qualifier.
2.3 /EXCEPTIONS_FILE
Specifies whether an exceptions file (file type .EXC) is to be
generated during the conversion.
Format
/EXCEPTIONS_FILE [=filespec]
/NOEXCEPTIONS_FILE (DEFAULT)
Specifies the file in which the exception records are returned.
If you specify /EXCEPTIONS_FILE but omit the filespec parameter,
the exception records are displayed on the SYS$OUTPUT device.
2.4 /EXIT
Controls whether the Convert utility exits when it encounters
an exception record. By default, the Convert utility continues
processing records when it encounters an exception record.
Format
/EXIT
/NOEXIT (DEFAULT)
2.5 /FAST_LOAD
Specifies whether the Convert utility uses a fast-loading
algorithm for indexed files.
Format
/FAST_LOAD (DEFAULT)
/NOFAST_LOAD
By default, the Convert utility uses the fast-loading algorithm,
but if CONVERT/FAST_LOAD is executed across a network, the
Convert utility automatically changes from /FAST_LOAD to
/NOFAST_LOAD.
2.6 /FDL
Indicates that an FDL file is to be used in creating the output
file.
Format
/FDL=fdl-filespec
Specifies the FDL file to be used in creating the output file.
The newly created output file will have the name specified by the
fdl-filespec command parameter; this name overrides any file name
specified in the FDL file.
The default file type for the FDL file is .FDL.
2.7 /FILL_BUCKETS
Controls whether to override the bucket fill percentage parameter
associated with the output file.
Format
/FILL_BUCKETS
/NOFILL_BUCKETS (DEFAULT)
If you specify /FILL_BUCKETS, the Convert utility fills the
output file buckets with as many records as possible. This option
is valid only for indexed output files.
2.8 /FIXED_CONTROL
Controls file conversions between files having variable-length
with fixed-length control field (VFC) records and files having
other record formats.
Format
/FIXED_CONTROL
/NOFIXED_CONTROL (DEFAULT)
This qualifier applies only to conversions where either the input
or the output file, but not both, uses VFC records. This option
is applicable only to sequential files.
o If you specify /FIXED_CONTROL and the input file uses VFC
records but the output file does not, the fixed-length control
field from the input record is inserted into the output record
as data.
o If you specify /FIXED_CONTROL and the output file has VFC
records but the input file does not, the leading part of the
input record is used to fill the fixed-length control part of
the output record.
o If you specify /NOFIXED_CONTROL and the input file uses VFC
records but the output file does not, the fixed-length control
field from the input record is not included as data in the
output record.
o If you specify /NOFIXED_CONTROL and the output file has
VFC records but the input file does not, the control field
attached to the output record is set to null.
2.9 /KEY
Directs the Convert utility to read records from an indexed file
using a specified key of reference, such as the primary key, the
first alternate key, or the second alternate key.
Format
/KEY=n
A numeric value that specifies the key of reference that the
Convert utility uses for reading records from the input indexed
file. For example, you can specify the primary key as the key of
reference by using the value 0 (/KEY=0), which is the default, or
you can specify the first alternate key as the key of reference
by using the value 1 (/KEY=1). The /KEY qualifier is valid for
indexed input files only. If you use the /KEY qualifier, you
must specify a key value (/KEY=0, /KEY=1, and so on). If you do
not specify the /KEY qualifier, the default is the primary key
(/KEY=0).
2.10 /MERGE
Specifies that records are to be inserted into their proper
position in an existing indexed file.
Format
/MERGE
/NOMERGE (DEFAULT)
The /MERGE qualifier is useful when your input records are not
sorted and you do not want them to be sorted as they are loaded
into an output file.
If you specify both /MERGE and /CREATE, /MERGE overrides the
/CREATE qualifier.
2.11 /PAD
Determines whether short records are to be padded.
Format
/PAD [=[%b]x]
/NOPAD (DEFAULT)
Specifies that the short records are to be padded with either
ASCII characters (A through Z, a through z, or 0 through 9) or
numeric values.
To specify x as a numeric value, you must specify the numeric
base using the percent symbol (%) followed by one of the
following characters:
D Indicates that x is a decimal number.
O Indicates that x is an octal number.
X Indicates that x is a hexadecimal number.
The numeric value can be any number from 0 to 255.
2.12 /PROLOG
Specifies the prolog version number of the output indexed file.
Format
/PROLOG=n
Specifies the prolog number 1, 2, or 3.
If you specify 2 for n, the output file will be either a Prolog 1
or a Prolog 2 file.
If you specify 3, the Convert utility creates a Prolog 3 file
for output. Prolog 3 files accept multiple keys (or alternate
keys), all data types, and segmented keys. The only restriction
to using a Prolog 3 file applies to files containing overlapping
key segments for the primary key. In this case, you would have to
use a Prolog 2 file. If you do not specify the /PROLOG qualifier,
the Convert utility uses the prolog version of the first input
file. If the input file is not indexed, the utility uses the RMS
default. To see what this default is on your system, enter the
DCL command SHOW RMS_DEFAULT.
The /PROLOG qualifier overrides the value given with the FDL
attribute KEY PROLOG.
2.13 /READ_CHECK
Specifies whether each input record is to be read from the file a
second time and compared to the record originally read.
Format
/READ_CHECK
/NOREAD_CHECK (DEFAULT)
2.14 /SECONDARY
Increases the Convert utility's performance by reducing the
number of required passes through the input data. This is
accomplished by placing alternate key information into the
CONVWORK file.
Format
/SECONDARY=n
Qualifier Value
n
Specifies the number of alternate keys that will be loaded to
the CONVWORK file with each pass through the input data.
This qualifier is valid when you are fast-loading a file with
more than one alternate key. This option allows CONVERT to use
more disk space for its work file than would be used by default.
The default number of alternate keys written to the CONVWORK
file is 1.
2.15 /SHARE
Specifies whether the input file is to be opened for sharing with
other processes during the conversion.
Format
/SHARE
/NOSHARE (DEFAULT)
You can use the /SHARE option to generate a rough backup of a
file that is always opened for sharing by some applications.
However, another process can alter the records during the Convert
utility operations. As a result, the consistency of the output
file cannot be guaranteed.
2.16 /SORT
Specifies whether the input file is to be sorted before being
loaded into an indexed file. The sort is done according to the
primary key of the output file.
Format
/SORT [=FORCE] (DEFAULT)
/NOSORT
Two procedures can improve the sort performance:
o Increasing the size of the working set for the duration of the
sort.
o Placing the input file, the output file, and the temporary
work files on separate disk devices.
By default, when there is a single indexed input file with
the same primary key definition as the output file, CONVERT
does not perform a sort of the primary key. If you specify the
keyword FORCE, it forces a sorting operation for the primary key.
If you specify /NOSORT with /FAST_LOAD, only the SORT of the
primary key is disabled. Alternate or secondary keys are
always sorted. The /NOSORT qualifier is useful when you know
the input file is already in primary key order.
2.17 /STATISTICS
Determines whether statistics about the file conversion are to
be displayed.
Format
/STATISTICS[=keyword]
/NOSTATISTICS (DEFAULT)
Keyword Meaning
BRIEF Displays a summary of the file conversion at the
completion of the operation.
FULL Displays summary information at the completion of
each key load containing Sort and Load statistics
for the key. A summary of the file conversion is
also displayed at the completion of the operation.
If you specify the /STATISTICS qualifier without specifying a
keyword, CONVERT defaults to /STATISTICS=BRIEF.
The statistics produced by the Convert utility upon completion
are as follows:
o Number of files processed
o Total records processed
o Total exception records
o Total valid records
o Elapsed time
o Buffered I/O count
o Direct I/O count
o Page faults
o CPU time
2.18 /TRUNCATE
Specifies whether records that exceed the maximum record length
for variable-length records, or records that exceed the specified
record length for fixed-length records, are to be truncated.
Format
/TRUNCATE
/NOTRUNCATE (DEFAULT)
If you specify /NOTRUNCATE and a long record is encountered, the
record is not written to the output file. If you specify the
/EXCEPTIONS_FILE qualifier, the entire record is written to the
exceptions file.
2.19 /WORK_FILES
Specifies the number of temporary work files to be used during
the sort process.
Format
/WORK_FILES=n
Specifies the number of work files you want. You can specify 0 or
any value from 1 through 10.
The default number of work files used during a sort is 2.
This qualifier is valid when you are fast-loading a file with
multiple keys or when you specify the /SORT qualifier. For more
information about sorting, see both the /SORT and the /FAST_LOAD
qualifiers.
2.20 /WRITE_CHECK
Specifies whether all writes are to be checked by comparing the
new disk records with the original records in memory.
Format
/WRITE_CHECK
/NOWRITE_CHECK (DEFAULT)
If you use this switch, each new record on the disk is read and
then compared with the original record in memory.
3 – Examples
1.$ CONV/NOCREAT/TRUNC/EXCEPTIONS_FILE=EXFILE VARFILE.DAT FIXFILE.DAT
This command causes the Convert utility to copy records from a
file with variable-length records (VARFILE.DAT) to a file with
fixed-length records (FIXFILE.DAT). Records longer than the
fixed length are truncated, and short records are copied to the
exceptions file EXFILE.EXC.
2.$ CONVERT FILE.IDX FILE.IDX
This command creates the output file FILE.IDX with a version
number one higher than that of the input file. The output file is
a copy of the input file, but it is a clean copy without bucket
splits, RRVs (record reference vectors), or pointers to deleted
records. The performance of the output file is also improved.
Note that the Convert utility establishes new record file
addresses (RFAs) during such reorganizations.
3.$ CONVERT/FDL=TEST.FDL TRNTO::DBA1:[EXP]SUB.DAT OUT.DAT
This command creates a new sequential file OUT.DAT with stream
record format at the local node, according to the specification
in the previously created FDL file TEST.FDL. The input file
SUB.DAT at remote node TRNTO is sequential with variable-length
record format. The Convert utility copies records from SUB.DAT to
OUT.DAT, changing the format of the records.
The contents of the FDL file TEST.FDL are as follows:
SYSTEM
SOURCE VAX/VMS
FILE
ORGANIZATION SEQUENTIAL
RECORD
BLOCK_SPAN YES
CARRIAGE_CONTROL CARRIAGE_RETURN
FORMAT STREAM
SIZE 0
4.$ CONVERT MASTER.DAT DENVER::DB1:[PROD]MASTER.SAV
This command creates a new file called MASTER.SAV at remote
node DENVER from the file MASTER.DAT at the local node. Because
the /FDL qualifier is not used, the new file has the same file
organization and record format as the original file. The action
of this CONVERT command is similar to that performed by the COPY
command. However, CONVERT transfers the file record by record and
thus does not use block I/O.
5.$ CONVERT/APPEND SALES.TMP KANSAS::[200,2]SALES.CMD
This command causes records from the file SALES.TMP at the local
node to be added sequentially to the end of the output file
SALES.CMD at remote node KANSAS. The file SALES.TMP is sequential
with variable-length record format, and the file SALES.CMD is
sequential with stream record format. When the Convert utility
loads records from the input file to the output file, it changes
the record format.
6.$ CONVERT/FDL=FIXED/PAD=0/TRUNCATE INFILE.VAR OUTFILE.FIX
This command creates the fixed format file OUTFILE.FIX and then
loads it with records from the variable input file INFILE.VAR.
Before they are loaded, any short records from the input file
are padded with an ASCII 0 character, and any long records are
truncated.
7.$ CONVERT/FDL=SYS$INPUT FORT.DAT STREAM.DAT
FILE
ORGANIZATION SEQUENTIAL
RECORD
CARRIAGE_CONTROL CARRIAGE_RETURN
FORMAT STREAM
<Ctrl/Z>
This command converts the FORTRAN carriage control file FORT.DAT
to a stream file that prints or types identically. The number of
records may differ, and the FORTRAN carriage control information
is removed from the records.
8.$ CONVERT/FDL=SYS$INPUT FORT.DAT VAR.DAT
FILE
ORGANIZATION SEQUENTIAL
RECORD
CARRIAGE_CONTROL CARRIAGE_RETURN
FORMAT VARIABLE
<Ctrl/Z>
This command converts the FORTRAN carriage control file FORT.DAT
to a variable-length record file. The FORTRAN carriage control
information is preserved as the first data byte, and the number
of records in the output and input files is the same.