Loading a File

The -load option creates an indexed file from a binary sequential file, a relative file, or a line sequential file. The command is:

vutil -load [-b|d|t] [-lnv(r|s)x] [-q] source destination

The source file is the name of the binary, relative, or line sequential file to read. The destination file is the name of the Vision file to add to. This file must already exist; it is used to determine the record size and key information.

By default, records from the source file are added to the destination file. If the -n flag (new file) is used, then any data in the destination file is eliminated before the records are loaded from the source file.

When doing a load, vutil places records that are rejected due to illegal duplicate keys into a file. Should this happen, vutil will report the name of the file that contains the rejected records. The format of this file is the same as a COBOL binary sequential file with variable-size records.

The input file is buffered according to the value in the A_SEQ_DEFAULT_BLOCK_SIZE variable. The variable must be set in the environment for vutil to use it. If the variable is not set, the default buffer block size is 4096 bytes. If the variable is set to "0", vutil -load into a sequential file will perform record-based I/O. If the variable is set to a positive value, that value will be rounded up to the power of two equal to, or greater than the value. This will be the buffer size in bytes. The maximum buffer size is 1GB.

By default, the source file is assumed to be a binary sequential file with an alternate format.

These are the source file format options:

-b

This loads a binary sequential file that is compatible with the ACUCOBOL-GT runtime into a Vision file.

If -v is not present, fixed-length records are read.

The -v option causes vutil to read variable-length records. The record length is stored in a two-byte record header.

-d

Records marked as deleted in the relative file are discarded.

The -v option is not allowed for relative files.

-l

You can use the -l flag to prevent vutil from locking the file if you need to allow simultaneous access to the destination file while vutil is operating. Normally, vutil locks the destination file to improve the performance of the load operation. When -l is not used, vutil adds records to the file using "bulk addition" mode, which generally runs faster.

-n

If the -n flag (new file) is used, then any data in the destination file is eliminated before the records are loaded from the source file.

-q

This option causes vutil to exit (with status 99) if user interaction is required.

-r

This option causes any duplicate key write errors to be retried as rewrites to the file. This option should be used with caution, because duplicate key write errors often indicate that an error exists in the target file description. Warnings about this problem are not seen when you use the -r option.

This option is incompatible with the -load -s option.

-s

This option indicates that duplicate records should be skipped rather than written to a file. When this option is used, any duplicate records found while loading the indexed file will be discarded.

This option is incompatible with the -load -r option.

-t

This loads a file that has line sequential format into a Vision file. This means that the source file is a simple text file, with records separated by line feeds. The source file may not contain any line feeds within the data fields, because a line feed denotes the end of a record.

This option implies -v (variable-length records), so the -v option is not necessary, although it is allowed. Line sequential files are assumed to contain variable length records. As such, they can only be loaded into Vision files that have been generated to accommodate the needed range of record sizes. If, however, the file contains records that are uniformly fixed length, the Vision file can be generated to accommodate only that fixed length. Should vutil attempt to load variable length records into a fixed record-size Vision file, an invalid record size error will occur. The error is reported as a generic parameter error.

-v

This option causes vutil to treat the source file as a file with variable-length records. The record length is stored in the record's header. The length of the header is either two or four bytes, depending on your machine type.

If -v is not present, fixed-length records are read.

-x

The -x option is required when you are working with binary sequential and relative files that contain variable-length records larger than 65,535 bytes. (These files store the record length in two additional bytes in the record header. For "vutil -load" to read these files, it is necessary to indicate that these extra header bytes exist.)

If you are creating this file for the first time, you can either use the "gen" option of vutil or write a COBOL program to create the empty Vision file. The -load function can be used to import data from another application.

If an error occurs, an exit status of 255 is returned.