Enscribe Programmer's Guide

Creating Unstructured Files
You create Enscribe unstructured files with the File Utility Program (FUP) or by calling either the
FILE_CREATE_ procedure or the FILE_CREATELIST_ procedure. When you create an unstructured
file, you must consider the buffer size and the disk extent sizes.
Buffer Size
The buffer size attribute lets you define the internal buffer size to be used by the disk process when
accessing an unstructured file. The buffer size attribute can be any of these: 512 bytes, 1 KB, 2
KB, or 4 KB.
When creating a file by using the FILE_CREATE_ procedure, you use the blocklen parameter to
specify the internal buffer size. When creating a file by using the FILE_CREATELIST_ procedure,
you use item code 44 in the item-list to specify the internal buffer size.
When creating a file by using FUP, you use the BUFFERSIZE parameter to specify the desired buffer
size.
When you open a file, the buffer size is automatically set to the value that was specified for the
file when it was created.
During program execution, you can change the buffer size dynamically by specifying either a
BUFFERSIZE value in a FUP ALTER command or by way of param1 in a SETMODE 93 procedure
call
Note that the FUP ALTER command also changes the BUFFERSIZE parameter contained in the file
label on disk. The SETMODE 93 call, however, applies only until you reverse it by using a FUP
ALTER command or another SETMODE 93 system procedure call or until the file is closed.
If you specify an invalid buffer size, then the next higher valid size is used. The default buffer size
is 4096, the maximum possible. Note that the buffer size you specify has no effect on the format
of the data. Only 4 kb is supported for 512-b sector devices.
Because the buffer size attribute in effect defines the physical unit of transfer, the most efficient
physical data transfers are those that start on a buffer-sized boundary and whose read count or
write count is an integral multiple of the buffer size.
A buffer size that is exactly the same size as the anticipated transfer size lets the disk process use
its fixed-length cache management scheme most efficiently. For example, if it is reasonable for
your application to read and write its data in 1024-byte quantities and on 1024-byte boundaries
(that is, the first block of data starts at RBA 0, the second at RBA 1023, the third at 2047, and so
forth), the best buffer size attribute to specify would be 1024.
For example, suppose that you let the disk process use the default buffer size of 4096 and your
application program naturally does its transfers in blocks of 1024 bytes. In such a case, each write
of 1024 bytes will cause the disk process to first read a block of 4096 bytes, modify 1024 bytes
of it in cache memory, and then write the 4096-byte block back to the disk. If the file is being
audited by TMF or was opened with a syncdepth greater than zero, then a large audit-checkpoint
(AC) record will also be generated because this appears to be a partial update to a 4096-byte
record.
If, instead, you specified a buffer size of 1024 and you are always reading and writing in multiples
of 1024, then each write of 1024 bytes will involve no read, a write of 1024 bytes, and no AC
record at all.
The performance difference in these two cases can be dramatic. The best practice for unstructured
files, whenever possible, is to always perform buffer-sized reads and writes starting at buffer-sized
boundaries.
Disk Extent Size
When you create an Enscribe file you can specify the size of the primary and secondary extents
(1 to 65,535 pages for a format 1 file, where a page is 2048 bytes). You can also specify the
Creating Unstructured Files 61