Convert database files to other file types
|
WTSupported in traditional Synergy on Windows
|
WNSupported in Synergy .NET on Windows
|
USupported on UNIX
|
|
fconvert [-switches] infile_spec [...] outfile_spec
Options
switches
(optional) An option string that determines general processing for fconvert. You can either prefix the whole string with a minus sign (for example, -xsv exceptfile) or prefix each option with a minus sign (for example, -x -s). The switches are as follows:
Change the default name of the exception file (for failed writes).
Display a processing summary on completion of fconvert.
Create all temporary files in the specified directory.
Display in-progress count of records processed where count is the record display multiple. If count is not specified, the display counter is throttled by a factor of 10 up to 100,000 records. If fast load optimization is occurring, an “Optimizing...” message is displayed.
Display the completion status as a percentage for all file conversions.
Display the online help.
A specification for the files to be converted, transferred, or modified. See infile_spec for syntax. You can specify more than one type of input file by specifying multiple infile_spec specifications.
A specification for the output file. See outfile_spec for syntax.
Fconvert converts, transfers, and modifies Synergy database files. In a client/server configuration, fconvert transfers and converts files directly to a remote host. If a remote host employs a different file structure from the client, fconvert automatically converts files to the host file structure. Network transfers are cached automatically. Fconvert can also modify the parameters of existing ISAM files.
Fconvert reads and writes data records to and from any of these file types (remote or local):
- ISAM
- Relative
- Counted
- Text (stream LF and stream CR/LF)
An infile_spec has the following syntax:
-infile_type [-infile_locking] [-infile_options] infiles
where
infile_type
Determines the file type of the input file or files that follow it:
ii = ISAM file
ir = Relative file
ic = Counted file
it = Text (native stream)
i1 = Text (stream LF)
i2 = Text (stream CR/LF)
infile_locking
(optional) An option that determines how the input files will be opened in fconvert:
Open the file exclusively using Q_EXCL_RO. (default)
Open the file with NO_LOCK set, so input-file locking does not occur.
(optional) Options that determine how fconvert handles records in a specified input file. You can either prefix the whole string with a minus sign (for example, -rt 50 for an input record size of 50) or prefix each option with a minus sign (for example, -r 50 -t).
Specify input record size.
Trim blanks from end of records until record size equals the output record size.
Suppress “Binary data” warning on 8-bit characters for sequential input files (infile_type of -it, -i1, or -i2). (Decimal values less than a space [32], except CR, LF, HT, and FF, will still cause a “Binary data” warning on an infile_type of -it.)
Specify key of reference for ISAM (default 0). This option is required when the output file -ak option is specified and there is more than one input key, to define the order for the autokey.
To cause an ISAM file using the /nonkey_sequential OPEN option to unload directly without an index for faster performance, use nonkey as the krf value. When using nonkey, keep in mind that any non-indexed output file will be unordered.
|
Whenever possible, fconvert will implicitly unload ISAM files using /nonkey_sequential. This behavior is only implicitly enabled under the following conditions: the input file is an ISAM file, the key being unloaded does not allow duplicates, exclusive file access is enabled (default), and the output file is an ISAM file. |
|
|
Infile_type must precede infile_locking and infile_options, and all three must precede the names of the files they define. |
infiles
The name(s) of the file(s) of the same type to be converted, transferred, or modified by fconvert. Separate multiple filenames with blanks.
An outfile_spec has the following syntax:
-outfile_type [-outfile_locking] [-outfile_options] outfile
where
outfile_type
Determines the type for the file created by fconvert. If o is the first character of outfile_type, fconvert creates a new file. If the file already exists, it will be replaced if you specify the -f outfile_options flag. If a is the first character of outfile_type, fconvert appends output to an existing file.
oi or ai = ISAM file
or or ar = Relative file
oc or ac = Counted file
ot or at = Text (native stream)
o1 or a1 = Text (stream LF)
o2 or a2 = Text (stream CR/LF)
outfile_locking
(optional) An option that determines whether the output file is opened with or without locking:
Open the file exclusively using Q_EXCL_RO. (default)
Open the file with NO_LOCK set, so output-file locking does not occur. Fast load optimization is turned off.
(optional) Options that define the way fconvert handles the output file. These options do not necessarily need to directly precede outfile.
Generate new autokey values. This option applies only to sequence keys, unless the FCNV_RESET_TIMEKEY environment variable is set, in which case it also affects timestamp keys. If you specify the -ak option and there is more than one input key, you must also specify the input file option -k krf to define the order for the autokey. See Autokeys below for more information about autokeys and implied -ak (reset).
Force an existing output file to be overwritten.
Specify the output record size.
Specify a description file. To create an ISAM file, you must specify a description file, which must either be a .par file (the output of the ISAM utility ipar) or an XDL file.
outfile
The output filename.
Fconvert can fast-load all of these input file types into an empty ISAM file (or an ISAM file that is being created). The fast-load operation is highly optimized for speed. If the output file is not empty, normal processing occurs. The fast-load operation requires that several temporary work files be created. These temporary files are created in the current directory by default. Use -t temp_directory to alter the location where temporary files are created.
|
Writing temporary files to a secondary disk may improve overall performance of the fast-load operation. |
Make sure sufficient free disk space is available wherever temporary files are to be created.
If change tracking is enabled for the input file, change tracking will be enabled for the output file.
Fconvert returns an exit status of -1 on completion if any read or write errors were reported or if any other errors terminate the utility; otherwise, it returns 0.
|
|
The fconvert utility operates on Revision 4 or higher files. To convert files to a lower or higher revision, set the ISAMC_REV environment variable before running fconvert. (See ISAMC_REV for more information.) |
ISAM files
To create an ISAM file from any file type other than ISAM, you must supply a description file. When creating an ISAM file from another ISAM file (a remote file, for example), fconvert uses the first input ISAM file structure by default. To override this default, use a description file; description files can be used to change the parameters of ISAM files (number of keys, record size, key characteristics, and so forth).
|
|
If you use fconvert to merge several files into one output ISAM file that you know may contain many duplicates, it is best to run isutl -ro to compress the data file after the merge. |
To convert a variable-length text file or variable-length-record ISAM file to a relative file, use -r recsize to specify the record size of the relative file (see outfile_options).
Counted files
The counted file is a derived file type; there is no equivalent Synergy DBL OPEN submode for counted files. You can, however, read or create a counted file using isload.
|
|
Files created with record sizes greater than 64K cannot be counted files. |
Text files (stream LF and stream CR/LF)
When specifying a text file, use the -it, -at, or -ot option for native stream files. To convert a Windows text file to a UNIX text file from a UNIX system, specify -it for the Windows file and -o1 for the UNIX output file.
|
|
We don’t recommend using text files that contain binary data (such as records containing integer fields or alpha fields that contain RFAs.) For example, when reading a record with an integer field that contains the value 2600 (0x0A28 in hex), fconvert will terminate the record when it encounters the 0x0A (LF) and start a new record with the next character. Therefore, as a precaution, a “Binary data (n) detected in file at nn” warning is displayed if binary data is encountered (excluding the CR, LF, HT, and FF line terminators). |
Exception files
Fconvert creates an exception file if an applicable error occurs (i.e., if any records fail to convert due to an “Illegal record size” or “No duplicates allowed” error). By default, the name of the exception file is outfile.exc, but you can specify a different name by using the -x option. You cannot specify a name for an exception file if you are converting more than one file.
If fconvert encounters an existing file with the name of the exception file it plans to use (either the default name or a name specified with the -x option), it will rename the existing file using the current timestamp and will create a new exception file if it runs into any failed writes.
The exception file is a counted file. Use fconvert to convert the records to another file format.
8-bit characters
When processing sequential input files, fconvert will detect and warn of possible binary data. The presence of binary data could cause premature record termination when the file is handled as a sequential file. (Note: You may be able treat the file as a relative file if the record size is a fixed length.) If you use 8-bit characters in your sequential files, you will want to specify the -8 option, which suppresses the warning message on ASCII characters above 127. This option must be specified for each input file for which message suppression is desired.
By default, all autokeys declared in the destination file preserve the original values coming from the input files, with the following exceptions:
- The value being loaded into a sequence key is always valid, except when it’s duplicate or zero. A duplicate value that matches a sequence already present in the file is reset to a value that is not a duplicate. A value of 0 generates the error “Sequence autokey 0 value cannot be preserved. Requires -ak reset or corrected input.”
- The value being loaded into a timekey is only valid when its evaluated datetime is greater than the year 2010 and less than one year from the current date. An invalid timekey will automatically be reset to the current datetime, and unless the binary value is equivalent to all blanks, zeros, or NULLS, a “WARNING!: Timekey reset, input timekey out of range” message will be displayed.
If the incoming data is known to contain invalid autokey data (which is typical if you’re adding autokeys to a new file at the location of an existing record), use the -ak option to generate new autokey values instead of preserving the invalid ones. Use of the reset or -ak option has the following behavior:
- The value being loaded into a sequence key is ignored, and the next sequence is generated for that key (starting from 1, or the SEED value if present).
- The value being loaded into a timekey is not explicitly reset unless the evaluated datetime is invalid. (See the beginning of this section for information on determining a valid timekey.) This reset behavior can be overridden by setting the environment variable FCNV_RESET_TIMEKEY=1.
Loading an input file into a destination file containing a sequence key, where the first record of the input file contains blanks, zeros, or NULLs at the record location of the sequence key, will reset rather than preserve the original sequence value, and will continue to reset all subsequent values as if -ak had been specified. We refer to this as an “implied -ak,” or a “reset.” As described above, timekeys are only reset when their evaluated datetimes are invalid.
Examples
The example below converts the ISAM file file1 to a relative file named file2:
fconvert -ii file1 -or file2
The following is an example of an fconvert command to transfer the ISAM file file1 and the relative file file2 to the ISAM file file3. If file3 does not exist, fconvert creates a file named file3 described by the parameter file file3.par. If file3 exists, fconvert overwrites it with a new file3. Fconvert displays a counter of processed records and a summary on completion.
fconvert -sv -ii file1 -ir file2 -oif file3 -d file3.par
The example below transfers file1 to remote host server1. If the file exists, it is overwritten with the new file. When the transfer is completed, a summary is displayed with statistics.
fconvert -s -ii file1 -oif file1@server1
In the following example, three similar sequential files named file1, file2, and file3 are loaded into the new ISAM file file4. The temporary file created during fast-load processing is written on a secondary disk E: in the work subdirectory. A completion percentage is displayed as the files are processed, and a summary is displayed at the end.
fconvert -s%t e:\work -it file1 file2 file3 -oif file4 -d file4.par
The example below loads the file isamfile.ism with records from file1.ddf and recognizes that there may be valid 8-bit ASCII characters in the file.
fconvert -it8 file1 -ai isamfile
