HP OpenVMS Systems Documentation

You can use the CONVERT command to transfer files to and from a remote node, either with or without modifying file attributes. If the output file exists, the Convert utility changes the organization and format of the input data file to that of the output file. If the output file does not exist, the utility creates it from the file attributes specified in an FDL file.

You can also use the Convert utility to copy files to or from a remote node without modifying file attributes. The Convert utility transfers the file record by record, just as it does on a single node. However, you must have NETMBX privilege to execute CONVERT commands over a network.

2.4 Exception Conditions

Certain conversions cause exception conditions. An exception condition occurs when a record from the input file cannot be placed in the output file because of some format incompatibility. The Convert utility sends a warning error message to SYS$ERROR upon encountering a record that causes an exception condition.

For example, an exception condition occurs when the length of the input records exceeds the length you specified for fixed-length output records. You can avoid this exception condition by specifying the /TRUNCATE qualifier. Converting short fixed-length records into longer fixed-length records also causes an exception. To avoid this exception condition, use the /PAD qualifier to fill in the output records. The /PAD qualifier allows you to specify your choice of pad character.

To keep a copy of the exception records, create an exceptions file with the /EXCEPTIONS_FILE qualifier. The exceptions file is a sequential file with variable-length records; it receives a copy of any record that cannot be placed in the output data file. Exceptions files have the file type .EXC, by default.

CONVERT Usage Summary

The Convert utility (CONVERT) copies records from one or more files to an output file, changing the record format and file organization to those of the output file.

Format

CONVERT input-filespec[,...] output-filespec

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.

If your process open-file limit is reached, or if RMS runs out of dynamic memory, then the file conversion prematurely terminates with an appropriate message.

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.

Exit the Convert utility by letting the utility run to successful completion.

Output from the Convert utility is directed to the file you indicate with the output-filespec parameter. For more information, see Section 2.1.

If you want to execute CONVERT commands over a network, you need NETMBX privilege.

CONVERT Qualifiers

This section describes the CONVERT command qualifiers used to select the organization and format of the output file.

/APPEND

Controls whether converted records from an input file are appended to an existing sequential file.

Format

/APPEND

/NOAPPEND (DEFAULT)

Description

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.

Example

$ CONVERT/APPEND N_Z_FILE.DAT A_M_FILE.DAT

      

This command causes the sequential input file N_Z_FILE.DAT to be attached to the end of the sequential file A_M_FILE.DAT.

Determines whether the Convert utility creates a file or uses an existing file for output.

Format

/CREATE (DEFAULT)

/NOCREATE

Description

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. To create an output file with the same characteristics as the input file, omit the /FDL qualifier.

If you specify the /NOCREATE qualifier, the Convert utility uses an existing file for output. You would use this option, for instance, to load records into a data file that you created previously with the Create/FDL utility.

Examples

$ CONVERT/CREATE OLDFILE.DAT NEWFILE.DAT

      

This command creates the new output file NEWFILE.DAT and loads it with the records from OLDFILE.DAT.

$ CONVERT/CREATE/FDL=UPDATE.FDL OLDFILE.DAT NEWFILE.DAT

      

This command creates the new output file NEWFILE.DAT and loads it with the OLDFILE.DAT records that have been reformatted according to the characteristics in the FDL file UPDATE.

Specifies whether an exceptions file (file type .EXC) is to be generated during the conversion.

Format

/EXCEPTIONS_FILE [=filespec]

/NOEXCEPTIONS_FILE (DEFAULT)

Qualifier Value

filespec

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.

Example

$ CONVERT/EXCEPTIONS_FILE=EXFILE.EXC/FDL=NEWFILE.FDL OLDFILE.DAT NEWFILE.DAT

      

This command loads the records from OLDFILE.DAT into NEWFILE.DAT and writes any records that cause exceptions into the file EXFILE.EXC.

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)

Example

$ CONVERT/FDL=NEWFILE.FDL/EXIT OLDFILE.DAT NEWFILE

      

This command loads the records from OLDFILE.DAT into NEWFILE.DAT and causes the Convert utility to exit if an exception record is processed. Because no output file type is specified, the Convert utility assigns the output file the same file type as the input file.

Specifies whether the Convert utility uses a fast-loading algorithm for indexed files.

Format

/FAST_LOAD (DEFAULT)

/NOFAST_LOAD

Description

The /FAST_LOAD qualifier is one of the most useful features of the Convert utility.

Note 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.

The /FAST_LOAD qualifier and the /NOFAST_LOAD qualifier both sort primary keys, and both qualifiers require multiple scratch disk files.

Essentially, the difference between the /NOFAST_LOAD option and the /FAST_LOAD option is the way records are inserted into an indexed file. The /NOFAST_LOAD qualifier uses the normal RMS Put service to load each record; RMS updates the indexes of both the primary and secondary (alternate) keys as each record is inserted.

The main disadvantage of using the /NOFAST_LOAD option is the slower system performance that results from bucket splits and updates to the index. As each primary key is inserted, any secondary keys for that record are inserted in the order of the primary key. In other words, the secondary keys are not inserted in order of their own keys. These unsorted secondary keys may eventually cause bucket splits; as a result, the index structure for the secondary keys may be less efficient.

The advantage of the /NOFAST_LOAD option is that the Convert utility does not attempt to sort secondary keys. Conversely, if you specify the /FAST_LOAD option, the Convert utility sorts the primary and the secondary keys.

The Convert utility processes a file as follows:

1. The primary keys are sorted. If the input file is on magnetic tape or if you specify multiple input files, the sort work file contains the sorted records. If the input file is on a disk, however, the sort work file contains only pointers to the sorted records.

   Note If your input records are already ordered by the primary key or if the primary key of the input and output files is the same, you should specify /NOSORT. This qualifier ensures that the primary keys are not sorted again. For more information about sorting, see the description of the /SORT qualifier.

2. The Convert utility builds the primary data record level from the sorted output file. The utility completely fills a bucket with data before it creates the lowest primary index level (the level 1 index). When an index bucket is filled, the Convert utility creates an index record in the next highest index level. If there is at least one secondary key, the Convert utility sends the first secondary key's value along with a pointer to the new output record to the Sort utility using the record interface. If there are multiple secondary keys, Convert sends as many of those keys up to the value specified by the /SECONDARY qualifier to a temporary file along with a pointer to the new output record for later sorting. This is performed in parallel while the primary key's data structures are being loaded.
3. When the Convert utility is finished with the primary key, it updates the associated KEY DESCRIPTOR in the file's prolog, closes any input files, deletes any temporary files and closes any input files. At this point, the utility has created a valid output file with records ordered by the primary key. If you specified no alternate keys, the Convert utility terminates.
4. The Sort utility is then called to sort the first alternate key (if one has been specified). These records were passed to sort during the load of the primary key.
5. The Convert utility loads these sorted pointers into the secondary index data record (SIDR) level and adjusts them to point to the records in the primary data level. Again, the utility completely fills a bucket with data before it creates the lowest secondary index level. When an index bucket is filled, the Convert utility creates an index record in the next highest secondary index level.
6. When the Convert utility is finished with this secondary key, it updates the associated KEY DESCRIPTOR in the file's prolog. At this point, the Convert utility has created a valid output file, containing sorted primary keys and secondary keys. If you specified no alternate keys, the Convert utility terminates.
   If there are additional secondary keys, the Convert utility calls the Sort utility to sort the temporary file on the next secondary key value. These records are then loaded to the output file as in steps 5 and 6 until all secondary keys have been processed.

The primary advantage of using the /FAST_LOAD option is that it is considerably faster than the RMS method used by the /NOFAST_LOAD option. In most cases, you can increase processing speed by a factor of 10. Even greater speed results when you load large files with many keys.

In addition, the index structure can be very efficient because each key is sorted before it is loaded. The only disadvantage is the large amount of disk space needed for the work files. However, you can control the amount of disk space by using the /WORK_FILES qualifier and by reassigning the work files to different devices. See the /WORK_FILES qualifier for more information.

Examples

$ CONVERT/FAST_LOAD UPDATE.DAT MASTER.DAT

      

This command loads the records from the file UPDATE.DAT into the output file MASTER.DAT using the /FAST_LOAD option. The Convert utility attains the added speed by building the indexes directly and then using RMS for block I/O only.

$ CONVERT/NOFAST_LOAD UPDATE.DAT MASTER.DAT

      

This command loads the records from the file UPDATE.DAT into the output file MASTER.DAT. In this case, the operation takes longer because the Convert utility uses RMS Put services to output each individual record.

Exit the convert utility by letting the utility run to successful completion.

Output from the Convert utility is directed to the file you indicate with the output-filespec parameter. For more information, see Section 2.1.

If you want to execute Convert commands over a network, you need NETMBX privilege.

/FDL

Indicates that an FDL file is to be used in creating the output file.

Format

/FDL= fdl-filespec

Qualifier Value

fdl-filespec

Specifies the FDL file to be used in creating the output file.

Description

The default file type for the FDL file is .FDL.

Example

$ CONVERT/FDL=INDEXFILE CUSTSEQ.DAT CUSTIND.DAT
      

This command creates the new file CUSTIND.DAT according to the specifications in the FDL file INDEXFILE.FDL. Records are then loaded from CUSTSEQ.DAT into CUSTIND.DAT.

Controls whether to override the bucket fill percentage parameter associated with the output file.

Format

/FILL_BUCKETS

/NOFILL_BUCKETS (DEFAULT)

Description

If you specify /FILL_BUCKETS, the Convert utility fills the output file buckets with as many records as possible. This behavior is advantageous if you do not plan to do random file processing, because using fewer buckets saves disk space and processing time.

With /NOFILL_BUCKETS, however, the Convert utility does not fill the buckets completely. Therefore, you can add records at a later date without splitting buckets or extending the file.

This option is valid only for indexed output files.

Example

$ CONVERT/FILL_BUCKETS SALES_DATA.DAT CUST_DATA.DAT

      

This command loads the records from the indexed file SALES_DATA.DAT into the indexed file CUST_DATA.DAT, filling the buckets of the output file with as many records as possible.

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)

Description

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.

When you use this qualifier, you must account for the size of the fixed-control area when you calculate the maximum size of the output record.

• 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.
• 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.
• 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.
• 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.

Example

$ CONVERT/FIXED_CONTROL VFC_FILE.DAT OUTFILE.DAT
      

This command loads the VFC records in the input file VFC_FILE.DAT into the output file OUTFILE.DAT.

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

Qualifier Value

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).

Description

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).

Example

$ CONVERT/NOCREATE/KEY=1 CUST_INX.DAT CUST_SEQ.DAT
      

This command loads the records from the indexed input file CUST_INX.DAT into the sequential output file CUST_SEQ.DAT. The records in the output file are ordered by the first alternate key in the input file.

Specifies that records are to be inserted into their proper position in an existing indexed file.

Format

/MERGE

/NOMERGE (DEFAULT)

Description

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.

Example

$ CONVERT/MERGE ACCOUNTS.DAT MASTER_INX.DAT
      

This command loads the records from the input file ACCOUNTS.DAT into the existing indexed output file MASTER_INX.DAT according to primary key values.

Determines whether short records are to be padded.

Format

/PAD [=[%b]x]

/NOPAD (DEFAULT)

Qualifier Value

x

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.

Description

The /PAD option is valid only for fixed-output record formats and is used to pad short records with ASCII characters or numeric values. A record is too short when it contains fewer bytes than the number of bytes specified for fixed-length records.

If you specify /PAD without a qualifier value, the default pad character is the ASCII null character (binary value 0).

Examples

$ CONVERT/NOCREATE/PAD=%X20 INFILE.DAT OUTFILE
      

This command specifies that any short records in the input file INFILE.DAT are to be padded with an ASCII space character before being loaded into the fixed-length output file OUTFILE.DAT.

$ CONVERT/FDL=FIXED/PAD=X 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. Any short records from the input file are padded with ASCII X characters before they are loaded into the output file.