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.