Using Bulk Addition

To use bulk addition on a file, open that file with the BULK-ADDITION phrase. For example:

OPEN OUTPUT MY-FILE FOR BULK-ADDITION

A file opened for bulk addition is locked for exclusive use by the program. This is necessary because the file becomes internally inconsistent when the first WRITE occurs and does not become consistent again until the file is closed.

You may use BULK-ADDITION with the OUTPUT, EXTEND and I-O open modes.

If you specify BULK-ADDITION for a file other than a Vision file, the effect is the same as if you had specified MASS-UPDATE instead.

Vision allocates a memory buffer for each file opened for bulk addition. The size of this buffer is controlled by the V_BULK_MEMORY configuration variable. The default size of this buffer is 1 MB. The default size is fairly large because it is assumed that only a few files will be open for bulk addition on a system at any one time. If this buffer cannot be allocated, the OPEN fails with a status indicating inadequate memory.

When a WRITE occurs for a file opened for bulk addition, only the record is actually written to the file. The keys for the record are not written out until later. When an operation occurs on the file other than a WRITE, that operation is suspended and all of the records with missing keys have their keys added. After this completes, the suspended file operation resumes.

The process of adding keys uses the memory buffer allocated when the file was opened. The algorithm is to fill the buffer with keys, sort them, and then add them to the file. This is repeated until all the missing keys have been added. The larger the memory buffer, the more efficient this process is.

When adding records to the file, Vision always places the records at the end of the file when using bulk addition. It does not re-used deleted record areas in this case. It does this to make the process of gathering the missing keys efficient. If you need to recover the deleted record disk space, you can rebuild the file with vutil to do this.

Note: Any operation on the file other than WRITE will trigger the addition of the keys. Ideally, this operation will be the final CLOSE of the file. In this case, all of the newly added records are keyed at once and efficiency is maximized. In the worst case, each WRITE is followed by some other operation (such as a READ). In this case, each record is keyed individually. This is less efficient than just updating the file normally.

This process of delaying the keying of the records has several effects besides improving performance. It affects the rules of COBOL, especially the handling of duplicate keys. In addition, it makes it harder to report the program's progress to the user, since much of the program's time may be spent in a single COBOL statement (the file's CLOSE, for example, may take the majority of the program's running time as it adds all the missing keys).